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METHOD AND APPARATUS FOR ADAPTIVE WEB SERVICES 

A portion of the disclosure of this patent document contains material which is 
subject to copyright protection. The copyright owner has no objection to the facsimile 

5 reproduction by anyone of the patent document or the patent disclosure, as it appears 
in the Patent and Trademark Office patent file or records, but otherwise reserves all 
copyright rights whatsoever. 

In the following description, for purposes of explanation, numerous specific 
details are set forth in order to provide a thorough understanding of the invention. It will 

10 be apparent, however, to one skilled in the art that the invention can be practiced 

without these specific details. In other instances, structures and devices are shown in 
block diagram form in order to avoid obscuring the invention. 

Reference in the specification to "one embodiment" or "an embodiment" means 
that a particular feature, structure, or characteristic described in connection with the 

15 embodiment is included in at least one embodiment of the invention. The appearances 
of the phrase "in one embodiment" in various places in the specification are not 
necessarily all referring to the same embodiment, nor are separate or alternative 
embodiments mutually exclusive of other embodiments. Moreover, various features are 
described which may be exhibited by some embodiments and not by others. Similarly, 

20 various requirements are described which may be requirements for some embodiments 
but not other embodiments. The detailed examples of the following pages are of an 
illustrative rather than restrictive nature, and some of the requirements referred to may 
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be requirements for a specific example and thus not limits on the spirit and scope of the 
invention. 
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1.1 Introduction 

In various embodiments, a goal of the Technical Preview 4 release of the Kinzan 
Technology Platform (KTP) is to provide web-based applications that are easily 
assembled and extended by developers and development partners with a wide 
variety of skills. 

The various components of the KTP Framework are intended to untangle the 
web of static and active content, style, structure, application logic, templates, 
servlets, and persistence mechanisms that is the norm in application 
environments that are driven by Java Server Pages (JSP). The result represents 
a major commitment to flexibility, extensibility, integrability, scalability, and 
reliability at all levels of application development. 

1.1.1 Assembling Is Easier than Building 

In one embodiment, the KTP is an open technology platform that enables rapid 
assembly, extension, and configuration of generic application modules based on 
Adaptive Web Services(AWS). In one embodiment, this is achieved by 
modularizing style, presentation, content, application logic, business logic, and 
services, and providing runtime capabilities that dynamically assemble these 
AWS. The result is a development and deployment environment that cleanly 
separates the various elements required to build these Adaptive Web Services. 
By separating these elements, teams can work more effectively, with various 
team members contributing to modules that require their skill sets, rather than 
requiring all team members to have multiple skill sets. 

The Kinzan platform enables the software engineer to work collaboratively with 
information architects, web developers, graphics designers, and customer 
advocates to create compelling network-based applications that can be delivered 
to various types of network devices (e.g., web phones, browsers, etc.) and with 
different branding and localization to different languages. 

The Kinzan platform also offers a series of abstractions that modularize and 
generalize application development at all levels of the application architecture. 
The result is an environment that enables modular assembly of applications from 
pre-built adaptive web services, while minimizing the amount of custom work and 
maintenance required for different customers. 
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1.2 Adaptive Web Services 

Kinzan believes that the next paradigm shift is to provide web services in the 
form of Adaptive Web Services. The KTP platform is designed and implemented 
with the intent of enabling developers with the framework and tools necessary to 
build and deploy these next generation services. We will move from a world of 
monolithic tightly coupled applications to a world of distributed loosely coupled 
applications comprised and built with Adaptive Web Services. 

When object oriented languages such as C++ emerged, more rapid application 
development could be realized because of code reuse and applications that are 
more reliable could be built because they could be tested at an object level. The 
limitation is that this technology requires very technical individuals to develop 
these applications. 

1 .2.1 Elements of Adaptive Web Services. 

The following diagram outlines the elements of an embodiment of an Adaptive Web Service. 
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Kinzan's Adaptive Web Services are comprised of five main elements: 
presentation, code, data, personalization attributes, and security. Each element 
of Adaptive Web Services will provide programmers and business people the 
ability to control the functionality of a service being provided to users. 

1.2.2 Adaptive Web Services Adaptability 

Kinzan's Adaptive Web Services are intelligent software components that can 
conform to how they are accessed and the context that the adaptive web 
services provide. Adaptability may exist in the following areas: 

• Adapts to devices accessing the service such as: TV's, PDA's, Cell Phones, 
etc. 

• Adapts to other Web Services that surround it and integrates via messaging 

• Adapts to language and locale of the browser 

• Adapts to location where it is loaded whether remote or local 

• Adapts to man-to man or man-to machine interface 

• Adapts to user (personalization). 
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1.3 Motivation 

Fundamentally, the KTP framework is intended to enable rapid branding, 
assembly, extension, and configuration of generic application modules. It does so 
by modularizing style, presentation, content, application logic, business logic, and 
services, and providing runtime capabilities that dynamically assemble these 
modules into rich applications. 

1.3.1 Market Drivers 

Current server-based application development technologies tightly couple 
presentation, content, and logic, making the modular development of brandable 
applications impractical. Each application becomes a one-time implementation, 
compounding support and maintenance issues going forward. 

Kinzan has a long history of delivering uniquely branded and configured Internet 
content and commerce-management systems to our customers on our hosted 
platform. The result is a deep understanding of application frameworks that 
enable the rapid branding and configuring of generic applications. 

Competitive pressures mean time to delivery is key. This places a premium on 
being able to rapidly and easily assemble, reconfigure, and extend generic 
applications. The global nature of the Internet also places a premium on easy 
localization and support for emerging alternative devices for Internet access 
(browsers, cell phones, PDA's, pagers, etc.). 

Finally, supporting an application development and deployment environment in a 
shared hosting facility requires robust security and reliability to support multiple 
applications and development partners simultaneously. 

1.3.2 Technology Drivers 

Even the most sophisticated technologies have limited value if they are too 
complex to use. There is a critical need to develop and package these 
technologies in a way that makes them accessible to teams with varying 
technical skills. 

Typical client-server implementations separate the client from the database. In 
the JSP world, that means direct connectivity between the JSP and the database 
via Java Database Connectivity (JDBC) queries (also known as Java Model 1 
architecture). 

With Enterprise Java Beans (EJB's), developers may abstract out business logic 
into a separate services layer using entity EJB's and session EJB's. However, 
that still leaves presentation and application logic in the JSP layer. In JSP 1.1, 

© 2001 Kinzan Inc. 
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using tag libraries helps to extract the application and presentation logic 
associated with common components out of the JSP; but the different elements 

c °- min 9led. Combining JSP's and servlets in a Model-View-Controller 
(MVC) configuration (also known as Java Model 2 architecture) alleviates some 
issues, but generally requires a higher level of complexity for all developers on a 
project. K 

The KTP framework (including rendering, state management, and services 
management processes) cleanly separates style, layout, presentation and 
content from application and business logic. It also supports localization and 
output to target deployment platforms with different capabilities (browsers cell 
phones, PDA's, pagers, etc.). 

The collection of files that make up a Kinzan Page Descriptor (KPD) is the 
"source code" that is "compiled" into a series of modular servlets (and associated 
da a), which are then dynamically assembled by the rendering engine at runtime 
In this way, developers can take full advantage of the power and performance of 
Java servlets, while benefiting from increased reuse and modularity and the 
clean separation of function and responsibilities in the development process. 

The Kinzan State Manager uses XML-based Kinzan State Diagrams (KSD) to 
connect and configure application logic modules, effectively assembling the 
controller tier of the application. 

The Kinzan Services Manager provides an abstraction layer for many kinds of 
back-end services and data and includes the ability to dynamically look up and 
bind to services. The result is modularization of the model tier. 

The KTP Framework is flexible. If developers choose to implement their pages 
close to the metal" as standard JSP pages or Java servlets, they may. However 

to do so is to give up the benefits of being able to apply different style and 

branding elements to a given application. In practice, developers will likely 
everage the KTP Framework for elements of their applications that require 
lexible styling and branding and apply conventional HTML, XML, and JSP 

techniques for sections where the flexibility is not required. 

The KTP framework is designed to support the development and deployment of 
closely related applications across multiple capability devices (browsers, cell 
phones, PDA's, pagers, etc.). 

As a practical matter, it is unlikely that there will ever be a painless way to 
simultaneously deploy a single dynamic web application to standard web 
browsers and a two-way pager with a 20-character display, no matter how 
sophisticated the development system. However, the KTP framework allows 
developers to rapidly develop and deploy closely related applications to platforms 
with different capabilities. By only needing to change the presentation modules, 
developers can leverage a common development methodology, business logic 
localization, and data persistence layers among all applications 
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1 .4 Kinzan Technology Platform Overview 

At the base is the Kinzan Infrastructure Platform. This represents the high- 
availability, high-scalability hosting infrastructure for the KTP. These data centers 
can be shared among many partners and customers, giving each access to more 
capacity and more reliability at less cost. 

The Kinzan Software Platform represents the core services and capabilities 
described in this document. It is a shared foundation for all applications built on 
top of the KTP. 

This core platform can also be extended by integrating in new services then 
exposing these services with widgets and KSD's. 

The modular nature of the KTP encourages reuse at all levels. Collections of 
modules (widgets, KSD's, and support modules) form libraries that may be used 
to streamline application development. 



1.4.1 Modular Assembly Approach 



KTP Modular Assembly 
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The KTP framework offers a modular assembly approach to page and application 
definition. By leveraging real-time modular assembly of pages by the Rendering 
System, and modular assembly and control of applications by the Kinzan State 
Manager, KTP-based applications are intrinsically extremely flexible and 
configurable. 

The modular assembly approach also empowers junior team members to 
assemble sophisticated applications, rather than having to code the various 
elements themselves. More importantly, it makes it practical to develop tools and 
applications that directly manipulate and configure other applications, 
empowering customers to maintain their own applications via "codeless" 
development. 

The KTP framework decomposes style, structure, presentation, active content 
branded assets, application logic, business logic, and various support services 
into distinct modules. Development team members contribute by developing 
modules that are appropriate to their skill set. These modules are then 
assembled to implement web pages and web applications. 

The Kinzan Page Descriptor (KPD) is the artifact that describes the modules to 
be used to assemble a page, and the Kinzan State Diagram (KSD) is the artifact 
that describes how pages and application logic are to be assembled into dynamic 
web applications. 

Although the KTP framework attempts to isolate dependencies between the 
various element types, there are, however, situations where rules are necessary 
to control the coupling between element types. Examples are included in the next 
sections. In these cases, the KTP framework allows definition of module variants 
that are bound to any combination of style, locale, and/or target device. Changing 
any of these instantly changes the module variant that is used when renderinq a 
page or driving the application. 
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1.4.2 Request-Response Architecture 
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Request-Response: Java Model 2 Architecture 



In the Java Model 2 architecture, Java Server Pages (JSP's) are used to query 
Enterprise Java Beans (EJB's) to generate a dynamic web page for a user. 
Different JSP's may be written to output different XML variants to support 
different kinds of devices. 



HTML is embedded in the JSP, along with the Java programming that is required 
to access the EJB's. Since sophisticated developers and sophisticated web 
designers are rarely the same person, it is often diff icult to support a collaborative 
development environment. 

When a user performs an action (say, clicking the check out button at an e- 
commerce site), the web page passes the action to a Java controller servlet. This 
servlet processes the action, stores information in EJB's if necessary, and then 
requests that the next appropriate JSP to be rendered. 



The KTP framework takes each of these layers and modularizes it. At the view 
layer, the Rendering Service dynamically assembles pages from all the modules 
that make up the page. Interfacing with the model layer is managed separately 
from the view layer, minimizing the impact on those that are more expert with 
graphics design and page presentation. 

The State Manager performs a similar function at the controller layer. Kinzan 
State Diagrams are used to dynamically assemble and configure application- 
logic modules called action components. Interfacing with the model layer is 
managed with action components, allowing information architects and site 
designers to more easily manage the configuration of application flow. 
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The Services Manager provides an abstraction and resolution layer on top of 
many kinds of services and components, making it easier for components and 
application-logic developers to take advantage of rich back-end services at the 
model layer with minimal programming. 
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1.5 The Component Overview . . . -i - 

Up to this point, we have spent a considerable amount of time explaining 
Kinzan's vision and how that vision solves problems for Kinzan's developers and 
partners. What follows is an explanation of the Component Architecture. 



1 .5.1 KTP Component Overview 
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KTP Component Overview 



The KTP Component architecture, as represented by the above figure, is 
structured so that the component loosely couples the 3 layers of the Model 2 
architecture. The component is comprised of a logical grouping of actions 
(Controller Layer), widgets (View Layer), and model beans (Model Layer). The 
sum of these three objects when executed by the State Manager, Rendering 
Service, and Model Manager make it possible for seemingly dissimilar objects to 
behave as one object to perform an action or some set of actions. 
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Additionally, the KTP architecture can be deployed in several different 
configurations thereby affecting the behavior and functionality of the components. 
One such configuration is to have the state manager and rendering service 
executing on the first tier (web server) with the rest of the objects executing on 
the middle tier (application server). Another possible configuration is to execute 
the state manager and rendering service on the first tier and model bean and 
service manager on the first tier or middle tier. This is made possible by Kinzan's 
innovative approach of integrating an internal EJB container into the KTP 
platform. Finally, armed with the knowledge of the EJB container being integrated 
into the KTP platform, we can deploy and execute the whole platform in the first 
tier. This gives the KTP platform added flexibility and scalability for the small yet 
diverse production facility and for the developers who are leveraging the KTP 
framework. 



We will discuss interactions among the State Manager (controller), Rendering 
Service (view), and Model Manager (model) in this section; subsequent sections 
will describe the specific features of each layer. 



1.5.2 Component Request 



MOTE: Figures in this section are sequenced such that the 
message numbering depends on previous figures. 




KTP HTTP Request 



The HTTP Request is in the form: 

http(s) : //address : port/ stateServletName/application/ksd/state?componentID=CID&EVENT=event 
where: 



stateServletName = alias for state servlet in the servlet runner 
application = name of the application/site in which the state diagram exists 
ksd = name of the state diagram to run 
state = state in the state diagram to run 
CID = ID for component to take action on 
event = name of the event to post 



Typically, an application that is in process will provide the CID, which 
automatically identifies the application, KSD, and event name to the state 
manager. The KSD also contains a default state so that state does not need to 
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be specified. The CID and event name are the keys, which allow the State 
Manager to identify the next state to execute or display. 




1.5.4 State Diagram Detail 

Furthermore, the user context is sent to the State Manager, which queries it to 
determine the appropriate actions to be performed by the state manager on 
behalf of the user. When all actions have been completed, the State Manager 
forwards the results to the rendering engine (servlet) which forwards it to 
whatever device the user sent the request. 

Example State Diagram: 

<ktp:stateDiagram name=" Login" startState="Login* directAccess=" false" visibility^ "public> 

<kcp:displayState name='Statel" kpd="KPDl" directAccess= " true" > 

<ktp: transition event=*Eventl" state="State2 " /> 

<ktp: transition event="Event2" state=*State3" /> 
</ktp: displays tate> 

<ktp : action name= "State2 " component= " net . kinzan. component . Component 1 "> 

<ktp: transition event="Event3 " state=*State3" /> 
</ktp:action> 
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<ktp:displayState name="State3 ° kpd=-KPD2" /> 

<ktp : action name= " f ai lure " component = "net . kinzan . component . Component 1 " > 
<ktp: transition event= n Event4 " states w State3 ■ /> 
<ktp: transition event= "Events " state=* f ailure2 " /> 

</ktp: action> 

<ktp:displayState name=" f ailure2 " kpd= "def aults/failure" /> 
</ktp: stateDiagram> 



1.5.5 Component Performing an Action 




KTP Component Performing an Action 



In the KTP an action is performed on behalf of the user when the State Manager 
executes a specific action. However, the State Manager may need to make 
changes to the model to perform the appropriate action on behalf of the user. For 
example, an action might need to update the stock symbols list for a given 
account. If this is the case, the action, through the component, should be able to 
obtain the appropriate business rules, which supply the appropriate model beans 
to make the required changes as depicted in the above figure. 
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1.5.6 Rendering the Compon nt 
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KTP Rendering the Component 

When the rendering servlet receives a request, it will determine the page 
requested from the URL of the request (the client will never directly access the 
rendering servlet), which is in the following form: 



^ir:r:t — :tsc*i;»:ti5'R::.t3saar*"uje::.5r;*»:.:f! .* 



itaemsnacsssiTnts-jr-ir: 



http: / /address : port/renderServletName/applicat ion/ kpd 



where: 



Jtaiwin*...* 



application = the name of the application from which this page comes 
kpd = the name of the page {Kinzan Page Descriptor) 



With this information, the component service is able to look up the required page 
in the database, find the root component of the page, and build the page. This is 
done by building each component on the page from the bottom up, allowing for 
bindings from parent components to child components to be resolved correctly. 
For each component built, the component service will perform the required 
bindings, calling the appropriate model beans for model data as necessary, and 
building the component tree so that the parent-child relationships are correct for 
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the current mode of each component. After the complete page is built, control is 
forwarded to the main body template of the page. This template has the variants 
about the device that is making the request and includes the nested templates 
that render the components on the page. This is done by obtaining the current 
widget for each component (set into the component by the component service 
based on mode), and getting the appropriate template for that widget by device 
type, locale, and style in the same fashion. Each template may also include other 
assets, such as images, obtained from the widget. Style is applied when the 
template is rendered by the JSP engine of the web server, as they are encoded 
to expand the appropriate tag attributes for the current style where required. 

The Widget 



Example of a widget: 

<ktp: widget name= "sampleWidget "> 

<!-- The attribute list defines bindable attributes in the widget. A class 
is automatically generated from the attribute list. — > 
<ktp: attributeList> 

<ktp: local name="text" type= n java.util.String"/> 
</ktp: attributeList> 



<!-- style, device, and locale attributes default true and indicate 

to the preprocessor whether such variants should be searched for 
<ktp : widgetTemplate>sampleTemplate . kwt< /widgetTemplate> 
</ktp:widget> 



The Widget Template 



Example of a Widget Template: 



<!- Sample KWT file for simple widget example - 
<table> 

<tr><tdxktp: zone name=*zonel*/></td></tr> 
<trxtd><ktp: text text=*text* /x/tdx/ tr> 
</table> 

where : 



•Ktp:Zon© is a placeholder for other components to be mapped into *" 
•Ktp:Toxt places the value of the named attribute from the widget into the template with 
the appropriate styling for the current style. 



The Kinzan Widget Template (KWT) can be as simple as an HTML fragment or 
as complex as a JSP file. The KTP provides several tags which allow a template 
to access widget attributes, define appropriate actions to post to the controller, 
and defines zones to embed nested components. The loader processes the KWT 
into a JSP containing the appropriate JSP code to perform the required 
mappings. We will discuss mappings after first explaining Bean Managers and 
Business Rules. 



© 2001 Kinzan Inc. 
Page 18 



KInzan 



KTP Developer's Guide 



4348P003Z 



1.5.7 The Bean Manager 



3. Call Bean Manager 
to get Business Rule 



1. Query System for 
Bean Manager that wiU 



return the required 
Business Rule 



KinzanApp 



idllite 



1 4. Returns Business Rule 



w 



Business Rule 
(Session Bean) 



Bean Manager Interaction 



The rendering service, in performing bindings, may need data from the model as 
detailed in the above figure. This is obtained from model beans, which are 
returned by business rules, which are returned by bean managers. A bean 
manager is responsible for registering with the system the business rules it 
manages. These business rules, which are stateless session beans, are 
referenced in the KApp file in the model bean definition, along with the method to 
call and required parameters to obtain the requested model bean. The rendering 
service has this information available and is able to query the system to obtain 
the appropriate bean manager from which it can obtain the business rule 
required to generate the model bean. The business rules typically contains the 
business logic, which facilitates the formatting, filtering, or massaging of the data 
returned from the model in a useful format to the widget requiring it. Additionally, 
the rendering service may perform transformations to transform a given model 
bean or model bean attribute into the type required for binding to the widget 
attribute successfully. 

The following is an example of using a Bean Manager in the KApp file: 



<ktp : beanManager name= "SampleBeanManager " > 

The Bean Manager is referenced by name, for example: "SampleBeanManager n . 
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Note: 

Bean Managers run as services in the model tier. 



1.5.8 The Business Rule (1) 





S CaisBLEinessRJe's 
specified method vUth 
specied parameters to get 
modal bean 

9BtSBfffJeBean(param1, 



^^^^^^^ 



1 4. Returns Business FUe 



Business FUe 
(Session Bean) 



a Returns MdoH Bean 
(Entity Bean) 



Made! Bean 
Business Rule Interaction 



Example of a business rule class referenced in a KApp file: 



<ktp:modelBean name="sampleBean"> 

<ktp:rule name^sampleBusinessRule" method=~getSan\pleBean" /> 
<ktp:param name="paraml" type=" java . lang. String "> 

<ktp:from widget=*sampleWidget" attribute="texf /> 
</ktp:param> 

<ktp:param name="param2" type=" java . lang. String "> 

<ktp:from literal= w param2" /> 
</ktp:param> 
</ktp:modelBean> 



The model bean declaration also declares the business rule that will return the 
required model data as well as the method in the business rule to call, and the 
parameters to pass. At runtime, when the system is building the component, the 
business rule's method is called, and the parameters are passed to obtain the 
model bean data required. 
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1.5.9 The Business Rule(2) 

The following is an example of a Business rule class: 

public class SampleBusinessRule extends KinzanBusinessRule 
{ 

public SampleBean getSampleBean ( java. lang. String paraml, java . lang . String param2 ) 

InitialContext ic = new InitialContext () ; 

/ / Get home interface 
SampleBeanHome sbh = (SampleBeanHome) ic . lookup ( "SampleBeanHome" ) ; 
// Get remote interface to entity bean, paraml, param2 form the primary key 
SampleBeanPK pk = new SampleBeanPK ( ) ; 
pk.keyl = paraml; 
pk.key2 = param2; 

SampleBean sb = sbh. f indByPrimaryKey ( pk ); 
return sb; 

} 




Component Binding and Mapping 

The KTP component service, upon determining the current mode for a given 
component, needs to determine if in that mode, the widget has zones, which 
require nested components. If this is the case, then the component service is 
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responsible for mapping the child components and building them, so that when 
the widget template includes them, they will display correctly. 

Example of a Component binding and mapping from a KApp file: 



<ktp : componentModeLis t> 

<ktp : componentMode widget= * sampleWidget • > 

<ktp:zone name= w zonel " component="anotherComponent" /> 

< / Jctp : componencMode> 
</ktp:componentModeList> 



The component service is also responsible for binding data from the model tier to 
the widget attributes for display. 

1 .5.1 1 Component Security 
Component Mode Security (Level 2) 

A component builder can set up permissions on the modes of the component 
compile time. The application builder will be responsible for mapping application 
security roles to component permissions (Refer to Appendix A). 
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1.6 The Kinzan Application ^3 
1.6.1 The Kinzan Application Hierarchy 

Within the Kinzan Technology Platform, sites are arranged hierarchically. 
Resources may be inherited or overridden at each level. 

Each Kinzan Web site is actually part of a large hierarchy of sites. Resources 
associated with sites at upper levels are available to sites at all lower levels. 
Lower levels may provide their own variant for a resource, overriding the more 
global declaration. This hierarchical arrangement allows you to build libraries of 
resources, streamlining development and facilitating the reuse of common 
modules. 





KPD 



1 



Widget 



Generic resources visible to all applications and 
pages developed on the platform. 

Changes here are automatically and immediately 
applied throughout the hierarchy unless the 
resource has been overridden at a lower level. 

Resources associated with a particular site or 
application — template bundles that represent all the 
able to be branded resources in an application. 
Sites may also be bound to parent sites; all 
resources available to parent sites are recursively 
available to child sites. 

Resources required for rendering a particular page, 
including other KPDs (if necessary). Changes here 
occur only on the specific page 



Resources specific to a particular widget instance. 
This is the termination point of the KTP hierarchy. 



Resources at a lower level override identically named resources declared at a 
higher level. For example, if the platform provides a generic widget named 
stockQuote, and you want to replace it with a different implementation, you need 
only declare a new widget named stockQuote at a lower level in the hierarchy. 
You may decide to implement a different widget, one named myStockQuote for 
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example, using the new widget requires you to modify all references to 
stockQuote within the various KPDs in the application. 

This is not an issue when you are developing an entirely new application. 
However, it is more common to begin with a generic implementation of the 
application and customize it for a particular client. In this case, overriding the 
resource at the application level applies the customization to the entire 
application at once. 

At the same time, a resource may be marked such that overriding it is not 
allowed. This is useful for limiting the behavior of children sites. 



An application, or site, is described by the Kinzan Application file (KApp file). 
This file contains definitions for the various resources required by the application, 
and may include other KApp files to import their resources as well. Defined 
within the KApp file are styles, widgets, assets, components, and pages (KPD's). 
In addition, for an application, the domain name and document root that identifies 
the site are defined. Sample KApp files can be found in Appendix A. 

While the KApp file defines resources used at runtime, the runtime environment 
does not deal with the KApp file directly. Instead, the KApp file is read by a 
loader tool, the KApp Loader, which parses the resource definitions and loads 
them into runtime. The loader, run at the application compile-time, is also 
responsible for parsing KWT files into JSP files and resolving variants for assets. 
Whenever the KApp file is changed, the loader must be run to make those 
changes available to the runtime environment. This pre-processing allows the 
runtime environment to run more efficiently while maintaining its dynamic nature, 
and gives the application developer application resource definitions in a file 
format that is easier to modify and maintain than the database. 

At the same time, applications are fully dynamic in the runtime environment and 
can be manipulated and changed by appropriate tools without running the loader. 

1.6.3 Organizing Files and Folders 

The following illustration outlines the development directory tree structure 
convention used for the Kinzan platform. 



1.6.2 The KApp File and Loader 



domain 



parent site 
child site 

CD /childSiteDocRoot 
l=! childSite.kapp 




Kinzan State Diagram files. 
Images, JSPs. HTML, and 
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Cl /image 
Q/de 

CD /image 
Q/es 

CD /image 
D/ja 

CD /image 

□ /fr 

CD /image 
CD /spring 

Cl /image 
Q/fall 

Q /image 

Q/kgd 

!=■ home.kpd 

H. login. kpd 

i=. contactUs.kpd 
□ /kwt 

Q /companyDefauit 

Cl /spring 

□ /fall 
O /style 

!=■ companyDefault.style 
l= spnng.style 
[= falLstyle 



other asset variants that 
require dynamic resolution at 
run time based on locale, style, 
or target device. 



Kinzan Page Descriptor files. 



Kinzan Widget Template files. 



Server-side style files that are 
similar to cascading style 
sheets. 



The following illustration outlines the deployment directory tree structure 
convention used on the Kinzan platform 



webroot 

parent site 
child site 

Q/childSiteDocRoot 

(iEchildSite.kapp 

O /asset 
CD /image 
CD/de 



□ /es 



C3 /image 



CD /ja 



CD /image 



O/fr 



Cl /image 
r fr 

C] /image 



Q /spring 



The loader resolves these 
variants at compile time. So at 
runtime the file system is not 
searched. The page model can 
be queried to retrieve the 
correct variant's URI. 
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□ /image 
Q/fall 

□ /image 

□ /kwt 

□ /companyDef ault 

□ /spring 
Q/fall 

□ /resource 

□ /images 

□ /style 

1=: companyDefault.style 

spring.style 
!1 fall.style 

□ /kpd 

IS home.kpd 
iS login. kpd 
l^contactUs.kpd 



Kinzan Widget Template files. 



Images and other static assets 

Server-side style files that are 
similar to cascading style 
sheets. 



Kinzan Page Descriptor files. 



□ /sd 



i=i home.ksd 
1=; login.ksd 
IscontactUs.ksd 



Kinzan State Diagram files. 



At compile-time and at runtime, the search path for the site or application 
includes the search root for the site or application and for each of its parent sites. 
The search root defines where files for the site are located. The search order is 
as follows: 



1. Look for the file in the root/ [subdir ] directory. The type of file being 
searched for determines which subdirectory is searched. See the tree 
diagram (above) for specific information about the expected directory 
structure. 



2. Search through the library search path for the KApp Loader in the same 
fashion. 



For resources that support locale, style, and/or target device variants, their 
variants need to be placed in subdirectories within the appropriate c subdir] 
using the pattern [locale) / [device] / [style]. The loader will search through 
each of these directories to obtain the relevant variants for the resource. 
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1 .7 The Model Layer f • /-y^j^ 

The classic definition of ModelA/iew/ControlIer architecture describes the model 
layer as the internal workings of the software. Typically, this layer includes 
messaging, data storage, integration with legacy systems, and so on. 

In the KTP architecture, the model layer consists of the Services Manager and 
myriad services that are integrated into the Kinzan platform. Examples of 
integrated services include database systems; EJB, CORBA, and COM 
components; and external applications such as credit card processing systems 
and commercial package-tracking systems. 



KTP Overview 

Updated: January 9, 2001 
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1.7.1 Overview 

When you work within the model layer, you will typically develop an application to 
integrate into the KTP or develop the glue layer that will link an external 
application or service into the KTP. 
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Skill Level: 

Developing new services and integrating external services into the Kinzan 
platform requires intermediate to advanced Java programming skills. 

1.7.2 Developing Services 

When you develop a service, you will both develop an application and integrate it 
into the KTP or you will develop the glue layer that will link an already developed 
application or service into the KTP. 

Services may be local or remote. 

• Local services are collocated — executed in the same memory space as the 
application that includes them. Local services can also be considered 
proxyless. Proxyless services do not need to communicate with a back end 
to perform their functions; all the functionality is contained in the downloaded 
JAR. 

• Remote services are not collocated; invoking their operations requires 
remote calls. Remote services may be either proxy services or SOAP- 
enabled services. 

o Proxy services rely on the functionality residing in the back end to 
perform their functions. The classes in the downloaded JAR 
communicate with and invoke operations on a remote server. 

o SOAP-enabled services are supported within the native functionality of 
the platform. They do not require any JAR's to be downloaded because 
the platform automatically generates all classes that are required to 
communicate with the back end using SOAP. 

To integrate a service into the KTP, you must implement the KinzanService 
interface. This interface declares methods that initialize and close down a service 
as well as set and get the sen/ice name and the service manager for the service. 

The Genericservice abstract base class implements all of the methods 
declared in the KinzanService interface except for init { ) and f ini ( ) . We 
recommend that you extend the Genericservice class when you develop a new 
service rather than implementing the KinzanService interface directly. 

Note that accessor and mutator methods within the Genericservice class are 
assigned a visibility of final. setNameO and setserviceManagero are 
callback methods that set the name of the service within the framework before 
the init ( ) method is called. 

When you extend the Genericservice class, implement the init ( ) method, 
entering any one-time operations that must be performed before a user can 
access the service. For remote services, bootstrap the communications protocol 
in initO. 
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Implement the f ini { ) method to close down the service, terminate remote 
connections, and perform other one-time cleanup operations. 

Extend the class to include application functionality, perform calls to an external 
API, or call those functions in another class. Additional implementation details 
are dependent on the type of service or application being integrated. 

Creating a SOAP-Enabled Service 

In general, follow the procedures below to create a SOAP-enabled service: 

• Define an interface for the service. This interface should extend the 

KinzanService and the SoapService interfaces. (Note that SoapService is 

a marker interface, so no implementation is necessary. When the platform 
resolves a service that implements the SoapService interface, it 
automatically creates a runtime proxy for the service that implements the 
SOAP-specific calls.) 

• If your interface passes or returns Java objects, these objects should 
implement the seriaiizabie interface. 

• Implement the class for your interface. The class should extend the 
Genericservice class and implement the interface you defined above. 

• Handle all state changes and object communications through the interface. 
The generic limitations of all RPC mechanisms make this necessary. For 
example, it would be difficult to SOAP-enable the connection pool service 
because the connection pool makes direct calls to its connections. 

1.7.3 Deploying Services 

As they relate to the platform, there are two types of services: static and 
dynamic. 

• Static services are declared in the configuration file for the application, so are 
known to the application at startup. Static services may or may not be loaded 
into memory at startup. 

• Dynamic services are discovered at runtime. Dynamic services allow you to 
add functionality without shutting down the server. There are three types of 
dynamic services. 

Deploying Static Services 

Static services are declared in the XML configuration file for the application. 
Once the service is declared it becomes available for use at startup. It may be 
loaded into memory immediately (loadAtStartUp= ,, yes") or when it is needed 
(loadAtStartUp^no"). The following example declares the logging service and 
loads it into memory. 
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<service id="LoggingService" loadAtStartUp="yes "> 
<class>net . kinzan. logging. LoggingService</class> 
<attribute name="propert:iesFile tt 

value="@f ileURLPref ix@@warinirooc@/LoggingService. properties" /> 

</service> 

Deploying Dynamic Services 

Deploying dynamic services is a two-step process. 

1 . Register the service with one or more lookup servers. 

2. Deploy the service's files into the core repository. 
Registering the Service 

If an application needs to call a service that is not in its configuration file, it 
consults one or more lookup servers until it locates the appropriate service. 
Registering a service with a lookup server allows you to add functionality to an 
application without needing to stop and restart it. 

Leasing a Service 

Once a service is registered with a lookup server, it remains registered until you 
explicitly remove it from the service or until the server is rebooted. Alternatively, 
you may lease a service to the lookup server. A leased service is available for a 
specified period of time, after which it is automatically removed from the lookup 
server. 

NOTE:""" ' " * " 
As of this writing, the client site may still be able to use the 
service proxy after the service has expired. This will change 
when remote events are fully implemented. 

Using Multiple Codebases 

Using multiple codebases, it is not necessary to package the service proxy and 
its dependent classes in a single jar. Codebases function in a way that is similar 
to the CLASSPATH environment variable. Each codebase entry specifies a 
server and a jar. When the service manager resolves the class dependencies for 
the service proxy, it looks first at its CLASSPATH; if the dependency is not found, 
it looks at each codebase in the order specified in the registration file. 

Using the Registration Tool 

The registration tool is a command line utility that accepts an XML file as input. 
Use this tool to register and remove a service from one or more lookup servers. 
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Before you can use the registration tool, you must create an XML file to use as 
input. Following is a sample input file: 

<bootStrap> 

<group name=" Test Ins tance"> 

< lookupService>http : / / server_address rport / soap/rpcrouter< / lookupService> 

<service id="StockQuoteService" lease= M 1186400"> 

<codeBase>http : / /server_address:port /codebase/stockquote . jar</codeBase> 
<codeBase>http: / /server_address:port /codebase/weblogicSl . jar</codeBase> 
<codeBase>http: //server_addross:port/codebase/weblogicaux. jar</codeBase> 

<interface>com. kinzan. example .stockquote . service .StockquoteService</ inter face> 

<class>com.kinzan. example. stockquote. service. RemoteStockQuoteService</class> 
<attribute name= M propertiesFile" 
value= M http: / /servor_address rport Zcodebase/StockQuoteService . properties "/> 
</service> 

</group> 
</bootStrap> 

group Organizes services into groups. Each KinzanApp is associated with only one 

group. 

lookupSevice Specifies the location of the Lookup service. You can specify as many lookup 

services as you want; the registration tool contacts each specified lookup service 
and registers each sen/ice in the group. 

service Defines the service. The service id attribute must be unique within the group. The 

lease attribute is optional. Specify the lease value in seconds. 

CodeBase Specifies the location and name of the service proxy jar or its dependent classes. 
Codebase entries are not required for SOAP-enabled sen/ices. 

interface Specifies the interfaces implemented by this service. Be sure that each of the 
specified interfaces is implemented; the tool does not perform any checking. 

class Specifies the class name that implements the service proxy. 

attribute Defines one or more attributes for this service. 
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After creating the input file described above, use a command similar to the 
following to register the service: 

java com. kinzan.app. service . registration. Tool -R inputFile . xml 



1.7.4 Using Existing Services 

Once a service has been developed and deployed, it is available for use within 
the application. Most commonly, you will develop a widget that incorporates the 
service. For information on developing widgets, see section 1 .8.3. 
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1 .8 The View Layer ^ 

The classic definition of Model/View/Controller architecture describes the view 
layer as the visual representation of the state of the model to the user. 

In the KTP architecture, the view layer consists of widgets, Kinzan Widget 
Templates (KWT files), styles, and assets. Widgets are used by components to 
format a visual representation, which is then placed on a page in the form of 
Kinzan Page Descriptor (KPD) definitions. The Rendering Service gathers 
information from all these sources to render and display the page. 



KTP Overview 

Updated: January 9, 2001 




Controller 



State 
Manager 



'State Diagram 







Ia 





Request 



Forward 



Request Response 





pons* 



Adaptive Web Service 
^^^■Business Persona 



View 



Rendering 
Service 



!!_Jru 



□ 



SryU 



Business Rule 




Widget 



r6 

atabaa 
Sybaai 

import 



Database 
(Grade, Sybaae, LDAf) 



Service Proxy 



Services 
Manager 



1X1 X? 

Lookup Respository 



Registration 
Service 



Components 
(EJB. CORBA, 
COM) 

Application 
(ERP, CRM, 

Messaging 
(JMS.MQ, Tlbco) 

-O 

Internet 
(XML, SOAP, 

1 ^Kinzan 

Shared Services 
(Security, Auth.. 
Personalization) 



iniMUAML & Aovancea bcnpungp 



■Java & Advanced Programming* 



PROPRIETARY & CONFIDENTIAL • DO NOT 
DISTRIBUTE) 
O 2001, kinzan.com 



1.8.1 The Elements of the View Layer 

The elements of the view layer are responsible for rendering a contextually 
appropriate page and displaying it to the user. The view layer comprises the 
following main elements: 
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• Style file: Is an XML file that specifies style attributes, such as the fonts color, 
or table border size. 

• Assets: Leaf objects to be included on a page, including images, text, HTML 
fragments, sounds, and so on. Assets may have variants that are 
dynamically resolved based on the current style, locale, or target device. 

• The widget itself: A widget encapsulates a formatted and styled visual 
representation of data and has two parts: 

o Kinzan Widget Template (KWT) file: An XML file that governs the 

appearance of the widget. A KWT may have different variants based on 
device, locale, and/or style, and may contain generic zones for placing 
additional, nested components. 

o An XML definition of the widget, which includes declaring the widget's 
attributes and assets, as well as defining the name of the KWT to serve 
as the widget's template. 

A widget is typically a generic view, which by itself has no meaning. For 
instance, an example widget may be an "image with a caption" widget, which 
displays an image with a text caption underneath. However, the actual image 
and text to display would yet be undefined. The component is responsible for 
binding meaningful data to the widget, as well as mapping children components 
to widget zones, which allows for nesting of visual components. This is done in 
the component definition, as discussed in Section 1 .8.4. 

In addition to the component, one more view layer element is required in order 
for the rendering service to build a page that can be viewed by the client, and 
that is the Kinzan Page Descriptor, or KPD. The KPD is an XML descriptor that 
specifies the title of the page, the root component to place on the page, and the 
style to apply to that component. 

1.8.2 Widget Overview 

As stated previously, a widget is nothing more than a generic view and requires 
bindings to data to make that view meaningful. Such bindings can be as simple 
as a literal text string, or may be more complicated, such as an attribute from an 
entity EJB. In either case, the widget definition and template remains simply 
centered on providing a view, and should not include any business logic specific 
to any application. In some cases, it may be necessary to develop a more 
specialized widget that presents a specific view, but for most applications, a set 
of generic widgets will be able to provide the needed elements to generate the 
view required. 

1.8.3 Developing Widgets 

Developing a widget typically involves: 

• Declaring the widget in a Kinzan Application (KApp) file 
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• Creating a KWT fiie to govern the presentation of the widget 
Skill Level: 

Developing new widgets requires the same skills as in designing an HTML or 
WML page, depending on the desired target device. In more complex instances, 
some Java programming and JSP skill is needed. 

Widgets 

The first step in defining a new widget is to create a widget definition in the KApp 
file. The widget definition is an XML descriptor that lists the following items: 

Widget Attributes: Widget attributes define holders for data that can be bound 
to and displayed in the widget template. An attribute needs to be defined for 
each data element that the template needs to access. Each attribute definition 
takes the form: 

<ktp: local name=" caption" 

type=" java . lang . String" 
de£aultValue="This is a caption" /> 



where the name identifies the attribute, the type gives the java type of the 
attribute, and the optional defaultValue gives a default value to assign to the 
attribute if nothing is bound to it. This is useful when an a generic widget is 
defined where some attributes should be optional. For example, for an "Image 
with caption" widget and the above attribute definition, the component utilizing 
the widget may decide the default caption is satisfactory, and not bind another 
value to it. 

Widget Assets: Widget assets map an asset defined elsewhere in the KApp file 
(See Section 1.8.6) to a local name, making the asset available to the widget 
template. 

<Jctp:widgetAsset naitie="mylmage" asset="SampleAsset" /> 

The local name, given by the "name" attribute can be different from the asset 
name. 

Widget Template: The widget template file that renders the view for this widget 
is also specified in the widget definition. 

<Jctp:widgetTemplate style=" false" locale=" false"> 

ImageWi t hCap t ion . Jew t 
</ktp:widgetTemplate> 
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The widget template is loaded as an asset. Therefore, its definition is similar to 
an asset definition and includes the same attributes to signal the loader what 
types of variants exists. In this case, the definition defines that this template has 
no style or locale variations. By default, these attributes are "true". 

This completes the definition of a widget. The next step is to define the widget 
template itself. 

Widget Templates 

A widget template file, or KWT, defines the visual presentation of the widget 
attributes and assets. KWT files are JSP fragments, allowing them to define 
more complex java code in the template to control how the page is rendered. 
However, they can also be simple HTML (or WML, or whatever markup language 
is required for the target device), augmented by special KTP tags that allow 
access to widget attributes and assets, as well as defining the appropriate forms 
for interfacing with the KTP controller layer. 

Additionally, a KWT may have variants based on style, device, and locale. In this 
way, a component utilizing a given widget will automatically have views for the 
variant styles, devices, and locales that the widget supports. (Assuming that the 
other widgets and assets the component uses also support the same variations). 

A sample KWT is given below. 



The template is for an HTML display of the image with caption example we have been discussing. 

Line 4 Defines an image taken from the widget, named by the local widget asset name 

mylmage. 

Line 9 ^ ^ Defines some text to display, taken from the widget's caption attribute. 
Widget Template Tags 

As mentioned above, the KWT template is augmented by special KTP tags that 
are processed by the KApp Loader at compile time to generate the appropriate 



1 <table> 

2 <tr> 

3 <td> 

4 <ktp: image image= "widget .mylmage" /> 

5 </td> 

6 </tr> 

7 <tr> 

8 <td> 

9 <ktp:text text= "widget .caption" /> 

10 </td> 

11 </tr> 

12 </table> 
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JSP files. The KTP tags that are available to the KWT developer are described 
below: 



<ktp:zone name-" zoneHamo" /> 



This tag defines a zone in the widget by the given zoneName. The component 
utilizing this widget is responsible for mapping content to the zone. The zone is 
simply a placeholder, and can be positioned by the template designer as desired. 

' * - ■ . ». , t.^r . .... *i . . » ^ *...-,>__.- r- A 

<ktp:text text= "valued 

where va/ue is either a text literal or widget.widgetAttributeName. This will 
result in the text from the given widget attribute to be placed here, surrounded by 
styled font tags, if the device supports them. 



<ktp: image image^iaag-e" border ="b" width="w" height = M h"> 



where image can be a literal or widgetwidgetAssetName. This will result in the 
appropriate asset to be displayed here, with the appropriate variation at runtime. 

b, w, and h can be literals or widget.widgetAttributeName. These attributes are 
optional and may be ignored for certain devices. 



<ktp: form>-.</ktp: form> 

This tag will generate the correct form to post to the controller layer, including 
hidden variables required for the State Manager to function, and JSP code to 
name it uniquely for a page. It is not recommended you try to manually code the 
form tags. 

Inside the form, you can place: 



y«3»3«r!.*JT ; : - r^Lzz^rza.- kzti-jxiziz z^'z.*^.. t: . -^rt^r. 



<ktp: submit value=" value" image=* image" > 



where value is the value to post to the State Manager. 

image is an optional attribute that if specified will result in the submit button 
being an image. If image is specified as widget.widgetAssetName, then it will 
utilize the given asset. The javascript is generated automatically and keyed to 
the generated form name. This is not supported on all devices, and will be 
ignored. 

Additionally, any other tag can take on new meaning: 
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<ktp:tagNamo attributes .. . > 



where tagName can be any valid tag for the target device of the template. This 
will generate the stylized tag and search the attributes list for widget attributes. 
This is useful where you would like a certain attribute to be set from a widget 
attribute. For example: 

<ktp: input type="text" value= "widget . textlnputValue" /> 

would result in a text input box, where the value is set to the widget's 
textlnputValue attribute. 

Note that some of the tags require different formatting depending on the target 
device requirements. If a certain template is not functioning correctly, examine 
the output JSP for irregularities. It may be necessary to hand code the desired 
functionality. 

More detailed widget examples and their usage can be found in Appendix A. 

1.8.4 Components 

The component is responsible for binding useful data to the widget. For 
example, the KApp snippet below identifies the ImageWithCaption widget as the 
view for the "display" mode, and binds some data from a literal to the widget's 
caption attribute. 

1 <ktp:componentMode name=" display" widget = ■ ImagewTtli^^ 

2 <ktp : bindings> 

3 <ktp:binding widgetAttribute="caption"> 
A <ktp:from literal^ -This is a literal binding! "/> 

</ktp: binding> 



4 



Line 1 Defines the component mode (i.e. display) and specifies the widget that will 

represent this component in this mode (image with caption) 

*f a literal binding! • to the widget attribute caption. 

Bindings to widget attributes may also be from dissimilar data types, in which a 
transformation can be specified as an attribute to the from tag, which defines a 
data type transformation from the source of the binding to the correct data type of 
the widget attribute. 

For a more in-depth explanation of components, see "The Component Overview" 
- Section 1.5 of this document. For more in depth examples, refer to Appendix A. 
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1.8.5 Developing and Using Style Files 

The style file is an XML file that defines stylistic elements to apply to pages that 
reference the style. The format of the style file closely follows that used in 
Cascading Style Sheets (CSS), specifying a list of tags and the style attributes 
for each tag. Multiple classes may be defined in a style, allowing you to define 
variations of style attributes for given tags. 

For example, a company wants to use its corporate colors on the home page for 
most of the year. However, in the spring and fall of each year it sponsors special 
events and wants the home page colors to change at these times. Defining 
separate classes in the . style file for Default, Spring, and Fall color schemes 
allows you to quickly and uniformly change the visual attributes for a page, and 
across multiple pages. 

The Rendering Service applies the style transformation when the JSP file is 
compiled and executed at runtime. The style elements are stored separately from 
the JSP itself to allow runtime style configuration by the user, for example to 
allow the user to change the color scheme of the page. 

Style transformations occur on the server, so you can benefit from CSS-like 
capabilities without depending on CSS-enabled browsers. Fonts are supplied by 
the client installation. 



1.8.6 Managing Assets 

Assets include objects such as image files, HTML snippets, PDF files, Flash 
movies, and sounds. Assets have variants that are resolved at run time based on 
locale, style, and/or target device. 

Files that make up asset variants are stored in an /assets directory under the 
application's root, or somewhere else in the KApp loader's search path. Within 
the /assets directory, asset variants should be arranged hierarchically in 
[locale] / [style] / [target] order. The loader application is responsible for 
searching through these directories for valid variants and resolving them, so that 
at runtime, the rendering service can look up the required variant quickly. See 
section 1.6.1 for more information on the Kinzan site hierarchy. 

Assets are declared in the KApp file. Their definition includes a description and a 
list of variant files, each variant optionally specifying the type of variant that 
exists. A sample asset declaration is given below. 

1 <ktp: asset name ="SampleAs set "> 

2 <ktp:description>This is an example asset</ktp:description> 

3 <ktp:variant device=" false"> image/sample. gif </ktp :variant> 

4 <ktp:variant style=" false" locale=" f alse"> image/sample .wbmp</ktp: variant> 

5 </ktp:asset> 
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Line 1 Defines the asset and assigns it the name "SampleAsset" 

Line 2 Gives a description to the asset. The description does not affect the rendering of 

the asset, but may be useful to developers or displayed in a tool. 

Line 3-4 Defines possible variants for the asset. Note that while the loader application 

searches the file system for the actual variant files, the listing and attributes given 
help the loader to locate those variants. The device, style, and locale attributes 
of the variant tags signal the loader what types of variants exist. For this 
particular asset, the description describes two possible variant files that the 
loader will search for and associate with this asset. The first is named 
"image/sample.gif", for which style and locale variants exist, but not device. The 
second is "image/sample.wbmp", for which only device variants exist. 



1.8.7 Kinzan Page Descriptors 

The Kinzan Page Descriptor (KPD) is an XML descriptor that declares a page's 
title, style, and the root component that contains the page's content. A page's 
root component may be a simple leaf component, containing one widget, or a 
hierarchy of children components that form a complex view. The KPD definition 
is declared inside the KApp file. An example definition is given below. 

1 <ktp:KPD name="samplePage" title=- Sample Page"> 

2 <ktp:description>My sample page. </ktp:description> 

3 <ktp: component name=*sampleComponent" 

4 type="lmageWithCaption" /> 

5 </ktp:KPD> 

- ^^o^^r^ ^—^^.-^m^^^.^ _ ^^^^^^^ 

Line 1 Declares the KPD, giving it a name and title. The name is the handle that the 

rendering service uses to look up the page. 

Line 2 A description is given to the page. This does not affect the rendering of the 

page, but is data that may be used by tools so developers have a more 
meaningful description of the page. 

Lines 3-4 The component instance for the page is defined. In this case, the page is 

defining an instance of the component type ImageWithCaption, and naming it 
sampleComponent. The page may also reference an existing component 
instance. 

~ - ■ - ----- - ... - tfra«rfcj«Ta f A ' «*iCtf*8ai 



1.8.8 Rendering a Page 

The Rendering Service is responsible for dynamically assembling KPD's when 
requests are sent to the web server. This is done by looking up the root 
component of the page, and then building it and any children it may have. 
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The Rendering Service is fully dynamic, and may thus (with proper tools) be 
manipulated and configured on the fly, without having to recompile site pages or 
site modules. This rapid configurability is a key feature of the KTP Framework. 

The Rendering Service internally uses the Model-View-Controller (MVC) 
paradigm to render pages. 

The Model is the set of Java classes supplied with the widgets. These Java 
classes are responsible for creating the widgets, retrieving any data required by 
them and implementing any business logic. Note that internal to the rendering 
environment, all components (pages, widgets, containers, etc.) are modeled as 
widgets. 

The View is the visual representation of the widget. In the rendering system, this 
is embodied in the corresponding widget template KWT file, which is processed 
into a JSP file for the widget. When the processed KWT file is compiled into a 
servlet and executed, the servlet interrogates the widget and uses the data 
contained in the widget to create a visual representation of it. 

The Controller is the rendering servlet. The rendering servlet processes requests 
by matching a request to a model and view. 

Rendering a page involves several components. These are described below: 

Rendering Servlet: The rendering servlet processes requests to render pages. It 
forwards the request to the rendering service and invokes the appropriate 
sen/let/JSP for the page. 

Runtime Persistence Service: The Runtime Persistence service encapsulates 
all operations for the Runtime persistent storage as a service, where the page 
model is stored. The KApp loader application is responsible for loading the 
required data to describe the components, widgets, styles, and pages into 
persistent storage at compile time. 

Rendering Service: The rendering service is responsible for building the model 
of a page. It uses the Runtime Persistence service to retrieve data from the 
Runtime datastore. For each component on the page, the rendering service uses 
this data to create the corresponding widget. The page model is returned as a 
tree structure where the root of the tree is the page widget. 

Component Service: The component service is responsible for actually building 
the components on the page, performing the required bindings, and setting the 
appropriate widget for the component's mode. 

Widget: The widget object contains all the data required to render the widget. At 
runtime, a widget also provides access to all its defined attributes. 

Device Template: The device template is the main wrapper JSP for a given 
target device. The rendering service forwards to this JSP when it is done 
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building the components for the page. The device template includes the main 
root component of the page by including the template for the widget in the 
component's current mode, which was previously resolved by the component 
service when it built the component. This template, in turn, will include any 
children components in the same way. 

Widget Template KWT: The widget template KWT (once processed and 
compiled into a servlet) translates the widget attribute data that was bound to it 
into its visual representation. It may also include assets, and applies styling if 
required 
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1:9 The Controller Layer 



The classic definition of Model/View/Controller architecture describes the 
controller layer as the means by which the user provides input or changes the 
state of the model. 

In the KTP architecture, the controller layer consists of the State Manager, 
Kinzan State Diagrams (KSD files), and Action files. 
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1.9.1 Kinzan State Manager Overview 

The Kinzan State Manager is a powerful and flexible tool for assembling web 
applications. Using the State Manager, you can rapidly assemble web pages, 
typically Kinzan Page Descriptors (KPD's), and application logic to configure your 
application. 

The State Manager supports flexible application configuration by cleanly 
separating state management from the presentation layer and providing a 
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mechanism to chain application logic modules to connect application pages. It 
also provides for state management at the user and request level, avoiding many 
concurrency issues that plague less sophisticated state management systems 
(including duplicate request handling). 

Application logic is implemented in modules using Java objects called actions. 
These modules allow for "pluggable" components that you can assemble 
dynamically based on user input and the current state. Developing atomic 
components and chaining them together provides flexibility in modifying or 
customizing applications for different users. The State Manager also enables 
convenient and extremely powerful field validation by these components. 

The State Manager provides basic transaction management across actions, and 
makes it easy to link to business logic (usually Enterprise Java Beans (EJB's)) 
and various support sen/ices. 

Applications can have many mini-applications (or subroutines) within them, 
allowing for better logical segmentation of application functions. This 
segmentation encourages state diagram reuse within and between applications, 
streamlining application development. The State Manager supports coordination 
and handoff between state diagrams. 

Kinzan State Diagrams (KSD's) are defined using XML, allowing for flexible 
configuration of wizards by less sophisticated developers, with easy integration 
into support tools. 



1.9.2 What Is a State Diagram? 



A state diagram, represents discrete steps in an application flow with decision 
points that trigger transitions to different sections of the application. 



Display State A 
Get Credit Card 



—SUBMIT 



TRY AGAIN 




YES- 



Display State C 
Get Address 



Display State B 
Display Error 
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For example, in the figure above, the application begins in Display State A. When 
the user enters a credit card number and clicks the submit button on a form to 
generate a SUBMIT event, the application moves to Action State 1 . Action State 

1 processes the credit card number and forwards the result to Action State 2. 
Action State 2 applies business rules to the credit card processing result to 
determine whether the merchant will accept the credit card. 

If the rules in Action State 2 generate a YES event, control passes to Display 
State C, which presents the user with a form on which to enter an address. If the 
rules in Action State 2 generate a NO event, control passes to Display State B, 
which presents the user with a rejection message and provides the opportunity to 
enter another credit card number. 

In Display State B, if the user chooses to enter another credit card number 
(perhaps by clicking a Try Again link), a TRY AGAIN event is generated and 
control passes back to Display State A for the process to begin again. 

1.9.3 Advantages of Using a State Diagram 

HTTP is a stateless protocol. Once a web server transfers a web page to a web 
browser, it has no knowledge about how pages are related to one another. This 
is one reason why links are embedded within web pages instead of being 
managed by the server. 

You can use a state manager and state diagrams to describe sophisticated 
relationships within an application without needing to manage all sorts of tricks to 
manipulate the actual web pages. 

When you model applications using traditional state diagrams, you immediately 
benefit from enhanced documentation, manageability, flexibility, and reuse 
across applications. 

Using the example in the previous section, you could easily replace Action State 

2 with a different piece of business logic that changes the criteria used to 
approve or deny a credit card transaction. You could make the change by 
replacing a single component, rather than having to dig through a much larger 
piece of application logic distributed throughout presentation code. 

If, in the future, the application needs to be more sophisticated to support 
multiple approval components for different merchants, modifying the application 
would be straightforward. You could insert a piece of application logic between 
Action State 1 and Action State 2 to determine which of many possible approval 
components to invoke for a particular merchant and trigger that approval 
component, all without impacting the other components of the application (logic 
or presentation). 
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1.9.4 Components of the Kinzan State Manager 



The following figure represents the various components of the State Manager 
model: 
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Domain 

A domain is a collection of applications. All state requests should be made 
through this interface in order to support the inheritance of applications, state 
diagram, etc. between parent and child sites. 

Application 

An application is a collection of associated state diagrams, which can by 
themselves be thought of as mini-applications. Creating associations of state 
diagram provides a common deployment group for a particular application. You 
can define an application hierarchy, assigning parent-child relationships to 
applications. A child application inherits state diagrams, states, and transitions 
from its parent application. 

State Diagram 

A state diagram, is a set of states, events, and pointers to actions and pages. An 
example would be a Tax State Diagram or a Shipping State Diagram. 
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Stat 

A state is a location in the state diagram being managed by the State Manager. 

States may be either display states, which reference a KPD or URL, or action 
states, which reference an action for processing. 

Transitions 

States may have zero to many transitions to other states, which are triggered by 
various events. 

Exceptions 

Exceptions define catch statements for state diagrams. When an exception 
occurs during the execution of a state diagram, it may be caught and transfer 
control to another state. 

Properties 

States may also have properties associated with them as name-value pairs. This 
may be useful in configuring a shared piece of application logic (or Action State) 
for a particular application. 

1.9.5 State Manager Details 
State Manager 

The State Manager controls the execution of a domain. Based on a current state 
and an input event, it retrieves the next state object. If the state is an action 
state, the associated code executes using the current usercontext as input. The 
State Manager processes the resulting event and retrieves the next state object. 
This loop continues until a display state is triggered, at which point control returns 
to the calling code. 
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Display State A 
Get Credit Card 



Display State B 

Display Error 



Action\ 

State 2 



Credit Card State Diagram 



YES- 



Display State C 
Get Address 



»> 



Shipping Address 
State Diagram 



For example, in the above figure an ACTION from a web page, which passes 
some form variables with a SUBMIT event, invokes the State Manager. Because 
the application is in Display State A, the State Manager queries the transitions for 
Display State A to determine that control passes to Action State 1 on a SUBMIT 
event. Action State 1 retrieves the form variables from the request context and 
executes its application logic. 

The State Manager manages all state diagrams in an application. In the above 
example, a YES event from Action State 2 passes control to the entry point of the 
Shipping Address Wizard. 

1.9.6 State Types 

States may be associated with a display page or with an action. 

If the state is associated with a display page, the page is returned to the user and 
the State Manager waits for input. One output from this page is an event, which 
the State Manager uses to determine the next state. 

If the state is associated with an action, the action executes when the state is 
entered. The code returns an event, which the State Manager uses to determine 
the next state. 
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DisplayState 

The Dispiaystate class represents a state with an associated user-interaction 
page. The user-interaction page is referred to as either a KPD (using the kpd 
attribute) or as a redirect URL (using the forward attribute). Only display states 
are stored in a user's state history. 

ComponentState 



Is the component's display mode. 
ActionState 



The Actionstate class represents a state with an associated action. It contains 
a reference to an action, which is the interface for defining actions. 

Actionstates return events that signify what they have done. For example, a 

Processorder component might return OrderProcessed OrorderFailed.'ln 

addition, the Action can throw an exception to signify that an error has occurred. 

An Actionstate may also accept input and make a decision about the next 
appropriate output state. A simple example would be an Actionstate with the 
reseller ID of the user as its output event. You could use the reseller ID as an 
event to trigger the next state based on the ID of that reseller. 



1.9.7 Action 



The action interface defines a single piece of code that is associated with a state 
Its main method receives a context (which includes session and request 
information), performs an action, and returns an output event. This output event 
leads to another state, which may be either another Actionstate or a 

DisplayState. 



1.9.8 State Servlet 

The State servlet manages retrieval of the parameters from the form. It places 
the parameters into an object and passes them to the State Manager for 
processing. When the call to the State Manager returns, the State servlet 
dispatches a request to the resulting KPD file, or redirects to a new URL 
depending on what was returned by the State Manager. 



1.9.9 Typical Sequence of Events 

In a typical use of the State Manager, the action from an HTML form invokes the 
btate servlet, passing in the various form parameters and session information. 
The State servlet packages the input and passes it to the State Manager. 
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Note: The term "wizard" is used in the source code to refer to a 
state diagram. 

The State Manager retrieves the request. It expects to see parameters named 

net_kinzan_nextwizard, net_kinzan_nextstate, and 

net_kinzan_nextEvent. These constants should be pulled from the 
net . kinzan .state . stateData . java file and represent constants. It determines 
the next state by using the appropriate Domain, wizard, and state classes, 
which may be different than current wizard and current state. 

Alternatively, if the stateDate . request_context_seq_id parameter is set to the 
user context sequence ID of the form, the net_kinzan_nextwizard and 
net_kinzan_nextstate parameters are assumed to be the same as the current 
wizard and current state. The net_kinzan_nextEvent parameter still determines 
the next event. 

If the next state is an Actionstate, the state's action is retrieved and executed 
The resulting event is then used to retrieve the next state, which is then similarly 
processed. 

If the next state is a Dispiaystate, control returns to the caller, with the 
Dispiaystate as the return value. The State servlet then dispatches control to 
the appropriate KPD file (the display state defines a kpd attribute), or redirects to 
a new URL (if the display state defines a forward attribute). 



1.9.10 State Diagrams as Independent Mini- 
Applications 

One of the major design abstractions when using the State Manager is the state 
diagram. A state diagram is a set of states that act as an independent mini- 
application. Encapsulating these mini-applications encourages reuse within and 
between applications. For example, a Tax State Diagram for configuring tax rate 
may be accessible either from a store-install state diagram or from a central 
administration page. 

Decomposing an application into many mini-applications is useful and powerful, 
but it does create the need to coordinate control between state diagrams For 
example, if you use a Tax State Diagram in multiple areas of a web site, how 
does the Tax State Diagram know where to return when it finishes? The Tax 
State Diagram should not need to know what other states or pages might link to it 
and you should not need to hardcode the return state. Having to do so would 
negate many of the advantages of encapsulation. 

The State Manager automatically coordinates interaction between state diagrams 
by maintaining a call stack that tracks state diagram start and end states . 
When a state diagram reaches its own end state, the State Manager returns 
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control to the state that called the state diagram. Alternatively, the state that 
called the state diagram may give the State Manager an explicit return location. 
To use this feature without needing to hardcode a state diagram's return state, 
transition to #end, when you want to exit your state diagram. 

The State Manager determines the return location for a state diagram in one of 
two ways. If a request to that State Diagram is made with the parameter 
stateData.REQUEST_RETURN.URL, the value of this parameter becomes the 
return location of the wizard. If no such parameter exists, the state prior to 
entering the new state diagram is set as the return location of the state diagram. 

In either case, when the #end state is reached, the return location is retrieved by 
the EndstateAction, which directs the State Manager to move to that location in 
the state diagram. 

Below is a list of classes used to implement this feature, along with descriptions. 
EndStateAction 

The EndstateAction is an Action that redirects the application to the state 
diagram's return location. To do this, it checks for a return location in the 
Retumstack. If it finds one, it throws a JumpTostateException constructed with 
the return location. The State Manager catches the JumpTostateException, 
extracts the return location from it, and directs the application to that state. The 
EndStateAction in TP4 is built into the State Diagram by a transition to #end. 

ReturnStack 

The Retumstack encapsulates a stack of return locations for an application 
session. It is important to have a stack (rather than a single variable) because 
State Diagrams may call other State Diagrams, and each has a different return 
location. Without a stack the return location would be overridden with each new 
transition. 

JumpTostateException 

A JumpTostateException directs the State Manager to move to a new state, 
circumventing the event-driven state transition model. An Action may throw this 
exception whenever it needs to move to a state that cannot be reached by any 
transition. 

1 .9.1 1 Usage Scenarios 

This section explores the kinds of things that you can do with the State Manager. 
It examines various problem scenarios and how to apply the State Manager to 
solve these problems. In the process, we introduce some advanced features of 
the State Manager. 
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1 .9.1 1 .1 Overloaded Form Processor 

This example looks at a common scenario when doing server-side processing of 
form data. Consider the case where a single form returns two addresses: one for 
receiving payments and one for the physical store location. Hitting submit on this 
form returns control to the server, which retrieves form variables from the page 
and updates the addresses in the database before redirecting to another page. 

The following diagram depicts this situation. One HTML page has essentially two 
separate sets of information in its form. It submits to the server, which then 
executes two address updates using a common processor. 



But what happens if a new reseller decides it wants to collect and update the 
payment and physical addresses on separate forms? The obvious solution is to 
write two new form-processing scripts and two new HTML pages to get this 
functionality. This is tedious, error-prone, and makes maintenance and upgrades 
more difficult. 

The State Manager allows you to redesign this part of the application. Rather 
than having a single form processor for all the information on the form, you can 
write two individual actions to perform the two distinct database updates. Once 
you divide the form processor code into two parts, you have a lot more flexibility. 

One option is to keep the same user interface. One HTML page has the form 
parameters needed for the two components. Submitting the form on the HTML 
page moves to the first action state, which performs its database update and 
then sends execution to the second action state. 



Using the same code components, we can now easily meet our reseller's request 
to divide the Ul into separate forms. 




Overloaded Form Processor 




Separate Components 
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Here is another reseller scenario. The following diagram depicts form 1 (payment 
address) posting to the action for updating the payment address. After this, the 
user is directed to the second form (physical address). A submit from that form 
then calls the action for updating the physical address. 




Separate Components, Separate Forms 



The State Manager enables this new level of flexibility. This example shows how 
a more modular, component-based system allows user interfaces to be more 
modular as well. Specifically, HTML forms that drive specific updates may be 
composed into a single page, or pulled apart into separate pages, while still 
sharing common application logic. 

Application Needs to Change Based on information Not 
Embedded In the State Diagram 

By allowing actions to return an event, which may then be used to drive the next 
state, the State Manager allows application flow to be affected by internal logic. 
Although most actions will probably either succeed or fail and proceed to the 
corresponding success or failure state, this is not a constraint. Actions may also 
direct the State Manager by returning any kind of event. 

Consider an example where two resellers share the same deployment of an 
application and require the application to behave differently. Using the address 
form situation from the first example, Reseller A wants a single form to drive both 
database updates, but Reseller B wants two distinct forms. 

The State Manager provides a straightforward solution to this situation. First, 
create a new action that has the Reseller ID of the current user as its output 
event. Then, use this component to drive the application to either of the 
alternatives. 

The following diagram depicts this situation. The Determine Reseller component 
is the first action state to which the user is sent. The Reseller ID, the output of the 
component, drives the application to the appropriate variant. Each variant uses 
common application logic, with changes constrained to the presentation layer. 
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Reseller Driving Application Variations 



Determining the reseller is just one example of how to control the application 
dynamically. Logical decision components can be added any time you need to 
change the application dynamically. 

1 .9.1 1 .2 Duplicate Request Handling 

Duplicate requests can be a major problem for web applications. The State 
Manager provides elegant duplicate request handling in a transparent way. 

What Is a Duplicate Request? 

A duplicate request occurs when a user clicks on a web page submit button more 
than once before the server returns a response, sending the same request to the 
browser multiple times. The client ignores the response of the first request and 
displays the response of the last request. 

Duplicate requests can be quite common. A user who clicks a button and does 
not perceive any change may grow impatient and click the button again. With 
web-based applications, this may happen quite often. 

Why Are Duplicate Requests Bad? 

Typically server processes are not programmed to identify duplicate requests, so 
the server processes both requests, perhaps attempting to perform some critical 
action (such as charging a credit card) more than once. 

Here is a picture of a duplicate request in terms of client-server interaction: 
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GO! 




-Request 1 
-Request 2 



-Response 1 
-Response 2 — 




Duplicate Request: No Handling 



Request 1 and Request 2 are identical and occur within milliseconds of each 
other— the result of a user double-clicking a submit button on a form. The server 
handles both requests, and both requests generate responses. The response for 
Request 1 does not make it to the client because the client is not listening for it. 
Instead, the client listens only for the response to Request 2, which it does 
receive. Both requests executed the critical code, which might make database 
tables inconsistent, charge a credit card twice, or cause other damaging side 
effects. 



Typical Duplicate Request Handling 

The above scenario, no duplicate request handling, is commonplace in web 
applications. To address the problem, some web application developers write 
specific functionality for duplicate-request handling into their server code. 
Typically this code checks for two requests made by the same user within a very 
small amount of time. If the server detects a duplicate request according to these 
parameters, it stops processing the duplicate request and returns an error 
message to the user. 

Here is a diagram of typical duplicate-request handling with more sophisticated 
web applications: 
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GO! 



ERROR! 



Client 



-Request 1 
-Request 2 



0- 



Response 1 
Response 2 — 




Duplicate Request: Common Handling 

In this case, the server has been safeguarded from the harm of a duplicate 
request because the duplicate request does not reach the critical code. It is, in 
effect, turned away at the door. 

This solution has its own issues though. The client receives only an error 
message informing him that he made a duplicate request. The server must return 
an error message, rather than the appropriate response, because the first and 
second requests were processed in two separate, disconnected threads. The 
second thread has no way of returning the response of the first request to the 
client, which would be ideal because the client ignores the response from the first 
request. 

Kinzan State Manager Duplicate Request Handling 

The State Machine architecture more properly handles duplicate requests. 
Because the State Manager maintains context information at the page and 
response levels, it can accurately detect duplicate requests and return the 
appropriate output to the client. 



GO! 




Client 



-Request 1- 
-Request 2- 



— Res 



Response 1 - 
Response 2 



Critical 
Code 



Server 



Duplicate Request: Handled Properly by the State Machine 
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The State Manager can accurately determine if a request is a duplicate because 
a userconcext object is saved with each request. The usercontext contains all 
of the form variables and values that belong to the request. A new request can 
be compared against the previous one, value by value. 

This is a great advantage over many duplicate-request determination algorithms, 
which simply look for two requests coming from the same user within a very 
small amount of time (usually milliseconds), and which do not consider the actual 
request values. These algorithms are only useful in handling the accidental 
"nervous twitch" double-click; they do not behave appropriately with the more 
common situation where a user is uncertain that the button click was accepted 
and decides to click it again several seconds later. 

The State Manager never actually produces any output; it redirects or forwards 
the user to a new location whenever processing reaches a display state. When a 
duplicate request is detected, the second request can find the display state that 
is the result of the first request (the one the user really wants to see) and redirect 
the client to that page. 

If the first request is not finished when the second request tries to find the result 
display state, the State Manager redirects the client to a temporary "Please Wait" 
page. This page refreshes automatically, checking the server again to see if the 
first request has finished. If it has, the State Manager will return the result state, 
otherwise it will return the "Please Wait" page again. 

The result is a very elegant and natural handling of duplicate requests. The 
server and user are safeguarded from the harm of duplicate requests, the user is 
advised of double-clicks (potentially avoiding future duplicate requests), and the 
user gets the appropriate response when the original request finishes. 

How do I setup my application to handle duplicate requests? 

When the State Manager detects a duplicate request, it throws a 
DuplicateRequestException. Your application state diagram should catch this 
exception and transition to a "Please Wait" page. Here is the state diagram XML 
to do this: 

<ktp : catch exception= " net . kinzan .state . DuplicateRequestException" 
state="pleaseWaif /> 

<ktp:displayState name="pleaseWait " forward=" /test/pleaseWait . jsp" /> 



The "Please Wait" page should give the user a message that the request is being 
processed. This "Please Wait" page has one requirement-that it generates an 
event named "WaitForDuplicateRequest". This instructs the State Manager to 
wait for the initial request to finish processing and, when it does finish, the State 
Manager will return the appropriate results to the user. 
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1.10 Logging Service 

The Loggingservice integrates the IBM JLog package into the KTP 
environment and implements two loggers: a trace logger and a message logger. 

• The trace logger is intended to be used by KTP developers as a debugging 
tool. 

• The message logger is intended to send messages to users of Kinzan- 
developed systems, such as system administration personnel and web page 
designers, and is capable of being localized. 

The trace logger and the message logger can each be run at the system level 
and at the application level. 



1 .1 0.1 System Loggers 

System loggers are visible across multiple KinzanApp instances. To access a 

System logger, use the GetSystemTraceLogger and GetSystemMessageLogger 

static methods. 



net/kinzan/logging/LoggingService. properties Stores system logger 

properties. If the system logger cannot locate this file, it defaults to full 
synchronized logging and sends output to the console. However, if the file exists, 
the output destination must be specified explicitly. 



1 .1 0.2 Application Loggers 

Application loggers are created by a specific instance of the LoggingService, 
therefore they are only visible within a KinzanApp. They can be accessed in the 
usual way: 



AppContext appContext = KinzanApp. getContext O 
Logger traceLogger = appContext . getTraceLogger () ; 

Use the application loggers whenever possible. They provide greater flexibility in 
that you can have different settings for each application logger. 



1.10.3 Logging Output 

You can configure each logger in the service to send its output to one or more 
supported devices. Currently supported devices include the console, files, and 
sockets. For each output device, you can configure its filter and message 
formatter. 
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1.10.4 Setting Properties 

The logging service supports the following properties: 

Logger .Description (optional) 

A brief description that identifies the logger. 

Logger . Organization , Logger . Product , Logger .Component, 
Logger. Server, Logger .Client (optional) 

Used by the formatters to assemble a line in the logger. 
Logger .Message .Mess ageFile 

Sets the path to the resource bundle the message logger should use. 

Logger . Trace . Logging, Logger . Message . Logging 

When the appropriate property is set to true, turns on trace or message logging. 

Logger . Trace . Synchronous p Logger . Message . Synchronous (optional) 

When set to true, the call to the Logger object becomes a blocking call. During 
development, you can set these to true, but in production, these values should 
be set to false. The default is false. 

Logger . Trace . Console , Logger . Message . Console 

When set to true, directs logger output to the console. The default is false. 

Logger . Trace . Console . Formatter, Logger . Message . Console . Formatter 

(optional) 

If Logger .Trace. Console or Logger .Message . Console are set to true, these 

fields specify the class used to format a message. Valid options are: 

• com . ibm . logging . EnhancedFormat t er 

• com . ibm . logging . EnhancedTraceFormatter 

• com. ibm. logging .TraceFormatter 

• net . kinzan . logging . SingleLineTraceFormatter 

Logger . Trace . Console . Mask, Logger . Message . Console . Mask 

Use these fields to set the message types that are allowed through the filter for 
the Console device. For instance, if you specified: type_exit type_leveli 
type_level3 for the Trace logger, only messages from the Trace logger with 
type exit, leveli, and level3 are displayed on the console. For valid type 
values, see the iRecordType interface. 

Logger. Trace. File, Logger. Message. File (optional) 

When set to true, directs logger output to a file. 
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Logger . Trace . File - FileName , Logger . Message . File . FileName 

if Logger .Trace. File Or Logger .Message . File are set to true, these fields 

specify the filename to which the logger writes messages. Do not use 
backslashes ( \ ) in your path, the JLog package does not like them. 

Logger . Trace . File .MaxFileSize , Logger . Message . File . MaxFileSize 

If Logger .Trace. File or Logger .Message . File are Set to true, these fields 

specify the maximum file size in KB. Once the file reaches this size, the logger 
creates a new one. The default is 1MB. 

When the system creates the first new file, it appends 1 to the original filename; it 
appends n+1 to each succeeding file (so myf ile . log becomes myf iiei . log, 
myf ile2 .log, etc.). 

Logger . Trace . File . MaxNoFiles , Logger .Message . File . MaxNoFiles 

If Logger .Trace. File or Logger .Message . File are set to true, these fields 

specify the maximum number of files that the logger should keep when it rotates 
the log files. 

Logger . Trace . File . Formatter, Logger . Message . File . Formatter 

See Logger . Trace . Console . Formatter 

Logger . Trace . File . Mask, Logger . Message . File . Mash 

See Logger .Trace. Console. Mask 

Logger . Trace . Socket , Logger . Message . Socket 

When set to true, the system directs log output to another machine. See the 
JLog documentation for instructions on setting up the server daemon that should 
listen to these messages. 

Logger . Trace . Socket . Server Name , Logger . Message . Socket . Server Name 
When Logger . Trace . Socket Or Logger . Message . Socket are set to true , 

these fields specify the server that messages are routed to. 

Logger . Trace . Socket . Port , Logger . Message . Socket . Port 

When Logger .Trace. Socket Or Logger .Message. Socket are set to true, 

these fields specify the port numbers that the logging daemon is listening to. 

Logger .Trace .Socket .Formatter, Logger. Message. Socket .Formatter 
Please see Logger .Trace. Console. Formatter 

Logger . Trace . Socket . Mask, Logger . Message . Socket . Mask 
Please see Logger .Trace. Console. Mask 

More information on these settings can be found in the JLog javadoc. 
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1.10.5 



Using the Logging Service 



StateManagerServlet, BasicLogComponent, RequestContext and 

staceEngine can now use the LoggingService. 

The KinzanApp object can be used to return the AppContext and thereby returns 
Logger objects. This is the Logger object defined in the IBM JLog package. 

Here is an example on how to use the class: 



// get loggers 

Logger traceLogger = KizanApp.getContext ( ) . getTraceLogger ( ) ; 
Logger messageLogger = KinzanApp. getContext (). getMessageLogger () ; 

traceLogger. text ( IRecordType .'TYPE_LEVEL1 , "MyClassName" , * MyMe thodName " , "Hi MOM!" ); 



• The standard name for the logging service is LoggingService. 

• Constant classes, such as IRecordType, are not implemented. 

• By convention, logger names are iTraceLogger and iMessageLogger. 



AttributeFiiter allows you filter any attribute on a LogRecord, either through 
inclusion or exclusion. 

The following JLog attributes are standard: 

• loggingClass 

• loggingMethod 

• organization 

• product 

• component 

• client 

• server 

The first two, loggingClass and loggingMethod, are typically the values you 
pass in to logger .entry, logger. exit, logger. text, logger . exception, etc. 
(The other five are typically configured on a per-LoggingService basis. They will 
become more important as we start deploying multiple web applications.) 



~"-«**&*:f*&£.iX+2. s .f'V.r.* 



Be sure to use the correct record type when you log entry and 
exit messages. This makes it easy to turn them on and off later. 
For exit logs, use IRecordType. type_exit and for entry use 

IRecordType . TYPE_ENTRY. 





1.10.6 



Filters 
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Using loggingciass and loggingMethod, you can include only specific classes 
and/or methods you want to see and filter out all others or the opposite, exclude 
specific classes and/or methods. 

The filter setting is in the default properties for both Giobaisystem and 
Loggingservice. They have been commented out, so the typical behavior is still 
in play. But if you uncomment the line below for desired LoggerName and 

LoggerType, you will activate the attributeFilter . 



#Logger . {LoggerName) . {Console | File | Socket } . Filter . attribute=loggingClass loggingMethod 
organization product component client server 

You can either exclude the listed attribute values or include them: 



Logger. {LoggerName) . {Console | File | Socket ) . Filter . ma tch= include 



or 



Logger. {LoggerName) . {Console | File | Socket } . Filter .match=exclude 



You can also specify an Any or All filter by setting the matchAii value - match 
one value of each attribute (either all attributes or just one). To match all 
attributes listed, use true or to match any attribute listed use false. 

Logger . {LoggerName) . {Console | File | Socket) . Filter .matchAll=true 

ir ll iv;>:;^ ^ W^^W!r^;^';;;:-if^v^ir:- ■ ........ . _ ... u ...... ^ ^.^.^ ^ „, 

For each attribute you can specify a space-separated list of values as an include 
or exclude list that must be matched by the logger. 

Logger. {LoggerName} . {Console | File | Socket) .Filter .attribute". loggingClass= ' 

net . kinzan . secur i ty . auth . module . JndiLoginModule 
Logger. {LoggerName} . {Console] File ) Socket) . Filter .attribute. logginMethod= 
Logger . { LoggerName } . {Console j File j Socket } . Filter . attribute . organization= 
Logger. {LoggerName) . {Console | File j Socket ) . Filter .attribute. product= 
Logger. {LoggerName) . {Console j File j Socket ) . Filter .attribute .component= 
Logger. {LoggerName} . {Console j File j Socket } . Filter .attribute . client = 
Logger. {LoggerName) . {Console j File | Socket } . Filter .attribute. server = 



1 .1 0.7 Additional Options 

You can define more than one logging service if you need to. The biggest 
disadvantage with this approach is that not all classes have access to a request 
context. In these situations, the code to get the Logging service becomes 
convoluted: 
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AppContext appContext = KinzanApp .GetAppContext ( " MyAppName " , null ); 

LoggingService loggingService = KinzanApp. GetService ( appContext, "MyFavoriteLogger " ) ; 

This implies that you have access to the Application instance name and the 
Logging service name. 
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Appendix A KTP Examples 



l. TextBox Component 



1.11 Introduction 



1.11.1 Audience 

This document is intended for developers who will be working with the Kinzan 
Technology Platform. It explains how to use the TextBox component. 

1 .1 1 .2 Overview 

This document describes the TextBox widget. This widget displays a 
text/password input file. 

1.1 2 TextBox Component 

1 .1 2.1 TextBox Widget Definition 

The GenericDataTable widget is defined in the file "simplegui.kapp". Here is the 
excerpt containing the widget definition. 

1 <ktp: widget name = "TextBox" > 



2 <ktp:attributeList> 

3 <ktp: local name="name" type=" java. lang. String" 
def aultValue= "TextBox** /> 

4 <ktp: local name=" is Pas sword" type=" java . lang. String " 
defaultValue="N" /> 

5 <ktp: local name="size" type=" java. lang. String" /> 

6 <ktp: local name="maxlength" type=" java. lang. String " /> 

7 <ktp: local name =" value" type=" java. lang. String" def aultValue=" " /> 

8 </ktp:attributeList> 

9 <ktp:widgetTemplate style=" false" 

locale= "false " >Gener icTextBox . Jcwt< /ktp : widgetTemplate> 

10 </ktp:widget> 

Line 1 The widget is defined with the name "TextBox" 

Lines 2-8 The attributes of the widget are defined and given default values (more below). 
Line 3 This attribute specifies the name of the text/password input field. 
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Line 4 This attribute specifies whether this component is a password field ("Y") or not 

("N"). 

Line 5 This attribute specifies the display size of the text/password field. 

Line 6 This attribute specifies the maximum allowed length of input to this field. 

Line 7 This attribute specifies the current value of the contents of the input field. 

Lines 9 The widget template. This points to the widget template file. There are no style 

or locale variants for this widget. However, there are device variants. 

1 .1 2.2 Device Variations 

The widget supports variants in html and WML. This is achieved by defining the 
appropriate variant templates for each of the widgets utilized in rendering the 
display for the component. 



file: simplegui .kapp 

<?xml version=" 1 . 0" ?> 

<!DOCTYPE ktp:kapp SYSTEM -http://www.kinzan.net/dtd/kapp.dtd 0 > 

<ktp:kapp name = "simplegui " xmlns : ktp="http: //www. kinzan.net "> 

<ktp : domainList> 

<ktp: domain name=" localhost" documentRoot= " simplegui " /> 
</ktp:domainList> 

<!-- Widgets --> 
<ktp:widgetList> 

<ktp: widget name="Text "> 
<ktp:attributeList> 

<ktp: local name="text" type=" java . lang . String" defaultValue="No Text 

Defined! " /> 

</ktp:attributeList> 

<ktp: widgetTemplate style= " false" 
locale="false">text.kwt</ktp:widgetTemplate> 
</ktp: widget> 

<ktp: widget name=" Image FromURL" > 

<ktp:attributeList> 

<ktp: local name="URL" type=" java. lang. String " 
def aultValue= " http : / /us . al . yimg . com/us .yimg . com/ i /my/hrt_l . gif " /> 

<ktp: local name= "width- type=" java. lang. String" def aultValue=" 60" /> 
<ktp: local name= "height" type=" java . lang. String" defaultValue="40" /> 

</ktp:attributeList> 

<ktp: widgetTemplate style=" false" 
locale= " false " > imageFromURL . kwt < /ktp : widgetTemplate> 

</ktp:widget> 
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<ktp:widget name= "Text Box "> 

<ktp:attributeList> 

<ktp: local name = u name" type=" java . lang . String" defaultValue="TextBox" /> 

<ktp: local name=" isPassword" type=" java . lang . String" def aultValue="N" /> 

<ktp: local name="size" type=" java . lang. String" /> 

<ktp: local name= "maxlength" type=" java. lang. String" /> 

<ktp: local name= "value" type=" java. lang. String" defaultValue= M " /> 

</ktp:attributeList> 

<ktp:widgetTemplate style= " false" 
locale=" false" >GenericTextBox. kwt</ktp : widgetTemplate> 

</ktp:widget> 

<!-- Dropdown list form --> 
<ktp: widget name="DropDownList"> 

<ktp :attributeList> 

<ktp: local name=" prompt" type=" java. lang. String "/> 
<ktp: local name=" listPostName" type=" java. lang. String" /> 
<ktp: local name='* listsize" type=" java. lang. String" def aultValue=" 1" /> 
<ktp: local name= "options" type= " java . lang . String []" /> 
<ktp: local name=" selected" type=" java. lang. String" 
defaultValue=" IThisNeedsToBeSet ! "/> 
</ktp:attributeList> 

<ktp:widgetTemplate style= " false" 
locale= " false " >dropDownList . kwt< / ktp : widgetTemplate> 

</ktp:widget> 

<ktp: widget name="SimpleList"> 

<ktp : attributeList> 

<ktp: local name=" listltems" type=" java . lang .Vector " /> 
</ktp:attributeList> 

<ktp:widgetTemplate style=" false" 
locale=" false " >SimpleList. kwt< /ktp: widgetTemplate> 

</ktp:widget> 

<ktp : widget name= " SimpleHashTableView" > 

<ktp:attributeList> 

<ktp: local name="hashTable" type=" java . lang . HashTable" /> 
</ktp:attributeList> 

<ktp : widgetTemplate style= " false" 
locale= " false" >SimpleHashTable . kwt</ktp : widgetTemplate> 

</ktp:widget> 

< / ktp : widgetList> 

<ktp: componentTypeList> 

<!-- The component name must be unique within this site --> 
<ktp:componentType name="Text" defaultMode="di splay "> 

<ktp:description>This is a very simple text component</ktp:description> 
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<ktp: actributeList> 

<ktp:reference names* text" widget= M Text" attributes" text " /> 
</ktp:attributeList> 

<ktp: componentModeList> 

<ktp:componentMode names "display" widgets "Text" /> 
< / ktp : componencModeLiso 

< /ktp : componentType> 

<ktp:componentType name=" URL Image" defaultMode="display"> 

<ktp:description>This is a very simple gui component</ktp:description> 

<ktp:attributeList> 

<ktp: reference name="URL" widget= ■ ImageFromURL" attributes "URL" /> 
<ktp: reference name= "width" widgets- ImageFromURL" attributes "width" /> 
<ktp: reference names "height" widgets" ImageFromURL" attributes "height" /> 

</ktp:attributeList> 



< ktp : componentModeLis t> 

<ktp:componentMode names "display" widget =" ImageFromURL" /> 
< / ktp : componentModeLi s t> 



</ktp: componentType> 



<ktp:componentType name="TextBox" defaultMode=" display "> 
<ktp:attributeList> 

<ktp: reference names-name" widgets "TextBox" attribute="name" /> 
<ktp: reference name=" isPassword" widget = "TextBox" 
attributed isPassword" /> 

<ktp: reference names" size" widget= "TextBox" attributes" size" /> 
<ktp: reference name="maxlength" widget="TextBox" attributes "maxlength" /> 
<ktp: reference name=" value" widget="TextBox" attribute="value" /> 
</ktp:attributeList> 



< ktp : componentModeLis t> 

<ktp:componentMode name= "display" widget = "TextBox" /> 
< /ktp : componentModeLi st> 
</ktp :componentType> 

<ktp:componentType name="DropDownList " defaultMode= "display" > 

<ktp:attributeList> 

<ktp: reference name= "prompt" widgets "DropDownList" attributes "prompt "/> 
<ktp: reference name= " listPostName" widget="DropDownList" 

attributes" listPostName" /> 

<ktp: reference names- lis tSize" widget="DropDownList" 

attribute="listSize"/> 

<ktp: reference names -options" widget="DropDownList" attributes-options" /> 
<ktp: reference name=" selected" widget="DropDownList" 

attributes-selected" /> 

</ktp:attributeList> 

<ktp: componentModeLis t> 

<ktp:componentMode names "display" widgets "DropDownList"/> 

< / ktp : componentModeLi s t > 
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< / ktp : componentType> 

< / ktp : componentTypeLi s c> 
</ktp: kapp> 

end of file: simplegui . kapp 
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2. GenericDataTable Component 

1.13 Introduction 



1.13.1 Audience 

This document is intended for developers who will be working with the Kinzan 
Technology Platform. It explains how to use the GenericDataTable component. 

1.13.2 Overview 

This document describes the GenericDataTable component. This component 
takes a set of tabular data and displays in the desired format. The data is bound 
from an EJB, obtained through a business rule (session bean). 



1 .1 4.1 GenericDataTable Widget Definition 

The GenericDataTable widget is defined in the file "genericdatatable.kapp". Here 
is the excerpt containing the widget definition. 

1 <ktp: widget name= "GenericDataTable "> ~ ' 

2 <ktp:attributeList> 

3 <ktp: local name=" content" type=" java.util .Vector" /> 

4 <ktp: local name=" header" type=" java .util .Vector" /> 

5 <ktp: local name=" footer" type=" java .util .Vector" /> 

6 <ktp: local name=" f irstCol" type=" java .util .Vector " /> 

7 <ktp: local name="lastCol" type=" java.util .Vector" /> 

8 <ktp: local name="defaultStyleClass" type=" java. lang. String " /> 

9 <ktp: local name="columnClasses" type=" java.util .Vector " /> 

10 <ktp: local name="rowClasses" type=" java .util .Vector " /> 

11 <ktp: local name="headerClasses" type=" java .util .Vector " /> 

12 <ktp: local name="footerClasses" type=" java .util .Vector" /> 

13 <ktp: local name=" f irstColClasses" type=" java.util .Vector* /> 

1 4 <ktp: local name=" lastColClasses" type=" java .util .Vector" /> 

15 <ktp: local name="dataTypes" type=" java .util .Vector" /> 

16 <ktp: local name="dataTypeClass" type=" java .util .Vector" /> 

17 <ktp: local name="dataTypePref ix" type=" java .util .Vector" /> 

18 <ktp: local name="dataTypeSuf f ix" type=" java .util .Vector" /> 

19 <ktp: local name="dataTypeReplace" type=" java .util .Vector " /> 

20 </ktp:attributeList> 
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21 <ktp:widgetTemplate style=" false" 

locale=" false">GenericDacaTable. kwt</ktp: widgetTemplace> 

22 </ktp:widgec> 



Line 1 The widget is defined with the name "GenericDataTable" 

Lines 2-20 The attributes of the widget are defined and given default values (more below). 

Line 3 The content of the table, represented as a vector of which each element is 

another vector (representing a row in the table). This is the only required attribute 
of the widget, it must have a value bound to it. 

Lines 4-7 The contents of the header row, footer row, and first/last columns. 

Lines 8-14 Vectors specifying style classes to be used in formatting the table and its 

rows/cells. The widget template will look for these style classes in the style file 
associated with whichever component implements it. 

Line 15 A vector of "datatypes". These are strings representing particular types of data, 

such as "StockSymbol" or "Pricelncrease". If the contents of "content" (line 3) 
make use of the GenericMetaData interface the GenericDataTable widget 
template can make use of this list of datatypes to associate the content of each 
cell of the table with a set of style classes and text changes (see 16-19 below). 

Line 16 A list of style classes corresponding to the contents of the "datatypes" list. These 

are the styles to use when displaying data of that type. 

Line 17 A list of prefixes corresponding to the contents of the "datatypes" list. A 

datatype's prefix will be prepended to the display content. 

Line 1 8 A list of suffixes corresponding to the contents of the "datatypes" list. A 

datatype's suffix will be appended to the display content. 

Line 19 A list of replacement text corresponding to the contents of the "datatypes" list. A 

datatype's replacement text will be displayed in place of the display content. 

Lines 21 The widget template. This points to the widget template file. There are no style 

or locale variants for this widget. However, there are device variants. 



1 .1 4.2 Device Variations 

The GenericDataTable widget supports variants in html and WML. This is 
achieved by defining the appropriate variant templates for each of the widgets 
utilized in rendering the display for the component. 



© 2001 Kinzan Inc. 
Page 70 



KiNZAN 



KTP Developer's Guide 



4348P003Z 



file: genoricdatatable . kapp 

<?xml version-" 1 . 0" ?> 

<!DOCTYPE ktprkapp SYSTEM "http : / /www. kinzan . net /dtd/ kapp . dtd" > 
<ktp:kapp name="genericdatatable" xmlns :ktp=" http: //www. kinzan.net •> 

<ktp :domainList> 

<ktp:domain name= - localhost - documentRoot="genericdata table" /> 
</ ktp : domainLis t> 

<!-- Widgets --> 
<ktp:widgetList> 

<ktp: widget name="GenericDa taTable u > 

<ktp:attributeList> 

<ktp: local name=° content" type=" java .util .Vector" /> 
<ktp:local name="defaultStyleClass" type=" java. lang. String - /> 
<ktp: local name^columnClasses" type=" java. util .Vector" /> 
<ktp: local name="r owe lasses" type=" java. util. Vector •/> 
<ktp: local name=" header C las ses" type=" java .util .Vector" /> 
<ktp: local name="footerClasses" type=" java. util . Vector" /> 
<ktp: local name="f irstColClasses" type= B java .util .Vector" /> 
<ktp: local name="lastColClasses" type=° java. util .Vector" /> 
<ktp: local name=" header" type=" java. util .Vector" /> 
<ktp: local name=" footer" type=" java. util. Vector " /> 
<ktp: local name="firstCol" type=" java. util .Vector" /> 
<ktp: local name="lastCol" type=" java .util .Vector" /> 
<ktp: local name="dataTypes" type=" java .util .Vector" /> 
<ktp: local name="dataTypeClass" type=" java. util .Vector" /> 
<ktp: local name="dataTypePref ix" type=" java. util .Vector" /> 
<ktp:local name="dataTypeSuf fix" type=" java .util .Vector" /> 
<ktp: local name="dataTypeReplace" type=" java .util .Vector " /> 

</ktp:attributeList> 

<ktp:widgetTemplate style=" false" 

locale=" false" >GenericDataTable.kwt</ktp:widgetTemplate> 
</ktp: widget> 
</ktp:widgetList> 

<ktp : componentTypeList> 

<!-- The component name must be unique within this site --> 
<ktp:componentType name =- Generic Da taTable" defaultMode="display"> 
<ktp : attr ibuteList> 

<ktp: reference name=" content" 

widget="GenericDa taTable" 
attribute="content" /> 

<ktp : reference name= "def aultStyleClass" 
widget= "GenericDa taTable " 
attribute="def aultStyleClass " /> 

<ktp: reference name="columnClasses" 

widget= "GenericDa taTable " 
attribute="columnClasses" /> 

<ktp: reference name= "rowC lasses " 

widget= " GenericDa taTable " 
attributes " rowClasses " /> 

<ktp: reference name="headerClasses" 
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widget= "GenericDataTable" 
attribute="headerClasses" /> 

<ktp : reference name= " f ooterClasses " 

widget= "GenericDataTable" 
attribute^" f oocerClasses" /> 

<ktp: reference name= " f irstColClasses" 

widget = "GenericDataTable" 
attribute*" f irstColClasses" /> 

<ktp: reference name=" lastColClasses " 

widget= "GenericDataTable" 
attribute="lastColClasses" /> 

<ktp : reference name=" header" 

widgets " Gener icDataTable - 
attribute*" header" /> 

<ktp : reference name = " footer " 

widget = "GenericDataTable" 
attribute=" footer" /> 

<ktp: reference name=" f irstCol" 

widget= "GenericDataTable" 
attribute="f irstCol" /> 

<ktp: reference name=" lastCol " 

widget = "GenericDataTable" 
attribute* "lastCol" /> 

<ktp: reference name="dataTypes" 

widget= "GenericDataTable" 
attribute="dataTypes" /> 

<ktp: reference name="dataTypeClass" 

widget= "GenericDataTable" 
attribute= "dataTypeClass • /> 

<ktp: reference name* "dataTypePref ix" 

widget* - GenericDataTable " 
attribute="dataTypePref ix"/> 

<ktp: reference name="dataTypeSuf f ix" 

widget*" GenericDataTable" 
attribute="dataTypeSuf f ix" /> 

<ktp : reference name* " dataTypeReplace " 

widget* "GenericDataTable" 
attribute* "da taTypeReplace"/> 

</ktp:attributeList> 
<ktp:componentModeList> 

<ktp:componentMode name= "display" widget= "GenericDataTable "/> 
< / k t p : c omponen tModeL i s t > 
< /ktp : componentType> 
</ktp:componentTypeList> 
</ktp:kapp> 

end of file: gener ictable . kapp 
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3» Weather Component 



1.15 Introduction 



1.15.1 Audience 

This document is intended for developers who will be working with the Kinzan 
Technology Platform. It explains some aspects of the KTP 4 component 
architecture by walking through an example component. 

1.15.2 Overview 

This document describes a simple Kinzan component-the weather component. 
The weather component looks up weather information based on an input ZIP 
code. The component is a simple component in that it has no extra classes in 
order to make it work. All of its functionality is described in the KApp, widget 
template and state diagram files. 

1 • i 6 Weather Compb^KilSSiSiii^^ 

The weather component is defined in a KApp file named weather.kapp. We will 
walk through the important elements of weather.kapp and see what they do. 

1 .1 6.1 Weather Widget Definition 

The first important piece of the weather KApp file is the widget definition. A 
widget is a view. It is completely independent from the data it displays. It may 
have multiple representations based on device and locale. 



I <ktp: widget name= "WeatherDisplay"> 
2 

3 <ktp:attributeList> 

4 <ktp: local name=" title" type="java. lang. String" defaultValue="Weather" /> 

5 <ktp: local name =" prompt" type=" java . lang. String" defaultValue="Enter Zip : "/> 

6 <ktp: local name="submitValuel" type=" java . lang. String" defaultValue="Go"/> 

7 <ktp: local name="submitValue2 " type=" java . lang . String" /> 

8 </ktp:attributeList> 

9 <ktp:widgetAssetList> 

10 <ktp:widgetAsset name="Go" asset="GoButton" overwriteable=" true" /> 

II </ktp:widgetAssetList> 

12 <ktp:widgetTemplate style=" false" 



locale= " false " >wea therDisplayTemplate . kwt< / ktp : widgetTemplate> 

© 2001 Kinzan Inc. 
Page 73 



Kinzan 



KTP Developer's Guide 



4348P003Z 



13 </ktp : widget> 



Line 1 The widget is defined with the name "WeatherDisplay" 

Lines 3-8 The attributes of the widget are defined and given default values. The attributes 
are defined in order that a component definition can bind particular values to 
them. Each of these attribute names corresponds to a template variable with the 
name ,l widget.<attributeName>". The widget template, 

"weatherDisplayTemplate.kwt", is included at the end of this document. Look at 
that and compare its contents with this segment of the KApp file. 

Lines 9-1 1 The widget asset list. This defines assets that are used by the widget, such as a 
button. Line 9 defines a Go button asset that is overwriteable. The 
overwriteabie attribute specifies whether or not the asset can be changed by 
derived widgets. 

Line 12 The widget template. This points to the widget template file. There are no style 

or locale variants for this widget. 



1 .1 6.2 Weather Component Definition 

The weather widget "WeatherDisplay" is the only view object that the Weather 
Component needs in order to display itself. It is now time, therefore, to define the 
component. The component has two modes-one that displays weather detail 
information and one that displays a weather forecast. Each defines the widget it 
uses (which is WeatherDisplay in both cases), and the bindings to that widget. 



1 <ktp:componentType name = "Weather" defaultMode= "display** > 

2 <ktp:description>This is a very simple weather widget .< /ktp :description> 

3 <ktp:attributeList> 

4 <ktp: reference name=" title" widget = "WeatherDisplay" attributed title" /> 

5 </ktp:attributeList> 

6 <ktp:componentList> 

7 <ktp: component name=" weather Image" type= "URL Image" /> 

8 <ktp: component name=" ziplnput" type="TextBox" /> 

9 <ktp: component reference="myLogin" /> 

10 </ktp:componentList> 

Line 1 The component type "Weather" is defined. It has a default mode named 
"display". 

Line 2 The component description. This does not affect the rendering system. 

Lines 3-5 The component has one attribute, title, which is bound to the value of title in 
the WeatherDisplay widget. 
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Lines 6-10 Lists the child components used by this component. The weather image and 
zipinput components will be instantiated for this component instance. The 
myLogin component is defined in another location (login. kapp). 

Now that the component attributes and child components are defined, the 
component modes are defined. Each mode of a component has one widget. 
The widget is topmost display component. Each mode then has a set of 
mappings, which bind child components into zones, and a set of bindings, which 
map data to widget or component attributes. 



11 <ktp:componencModeList> 

12 <ktp: componentMode names display" widge ts WeatherDisplay "> 

13 <ktp:zone names weatherlnfo" components" weather Image " /> 

14 <ktp:zone name=" inputArea" components zipinput " /> 

15 <ktp:zone name=" loginZone" component= "myLogin" /> 

16 <ktp : bindings> 

1 7 <ktp: binding component=" weather Image" attribute="URL" 
defaultValue="http: //209 .70. 191. lll/zipcode/9/90210 . gif "> 

18 <ktp:from userContext="url " /> 

19 </ktp :binding> 

20 <ktp: binding components weatherlmage" attribute= "width" > 

21 <ktp:from literal= ■ 150 " /> 

22 </ktp:binding> 

23 <ktp: binding components weather Image" attributed height ■> 

24 <ktp:from literal = "50V> 

25 </ktp:binding> 

26 <ktp: binding components zipinput" attribute= "value" defaultValue="90210"> 

27 <ktp: from userContexts zip" /> 

28 </ktp:binding> 

29 <ktp: binding widgetAttribute= "prompt "> 

30 <ktp:from bundle^ " com. kinzan. example. weather . Weather_res " 
attributes ENTER_ZIP"/> 

31 </ktp :binding> 

32 <ktp:binding attributes title"> 

33 <ktp:from bundles com. kinzan. example .weather . Weather_res " 
attributesTITLE" /> 

34 </ktp:binding> 

35 < / ktp : bindings> 

36 </ktp:componentMode> 



Line 12 A component mode is defined. The mode is named "display" and it uses the 

widget "WeatherDisplay". The mode name is referenced in the component's 
state diagram. This will be shown later. 

Lines 13-15 The zones of the WeatherDisplay widget are mapped to the child components of 
the Weather Component. 
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Lines 16-35 The attributes of the child components and widgets are bound to values. They 
can be bound to literals, user context attributes, resources bundle values, and 
other things. 

Lines 17-19 The url attribute of the weather image child component is bound to the user 

context attribute "URL". Line 17 also shows a default value for the URL attribute- 
-this will be used before the binding can be run. 

Lines 20-25 The width and height attributes of the weather image component are bound to 
literal values "150" and "50". 

Lines 26-28 The value attribute of the zipinput component is given the defaultValue 
"90210" and is bound to the usercontext attribute named "zip". 

Lines 29-31 The prompt attribute of the component's display widget (WeatherDisplay) is 
bound to the value found in the resource bundle 

com. kinzan . example . weather . Weather_res using the key ENTER_ZIP. 

Lines 32-34 The title attribute of the component is bound to the value found in the resource 

bundle com. kinzan. example, weather .Weather_res using the key TITLE. 

So far we have defined the first mode of the component. The component has a 
second mode, "forecastDisplay", that displays a five-day weather forecast. 

37 <ktp:componentMode name=" forecastDisplay" widget="WeatherDisplay> 

38 <ktp:zone name=" weather Info" component= ■ weather Image " /> 

39 <ktp:zone name= " input Area " component^" zip Input " /> 

40 <ktp:zone name= u loginZone" components my Login" /> 

41 <ktp:bindings> 

42 <ktp: binding component =" weather Image" attribute^ URL" 
def aultValue= "http://209.70. 191. Ill /forecast /9/90210 .gif "> 

43 <ktp: from userContext= "url " /> 

44 </ktp:binding> 

4 5 </ktp:bindings> 

4 6 < / ktp : componentMode> * 

47 </ktp:componentModeList> 



Line 37 The forecastDisplay mode of the component is defined. It also uses the 

WeatherDisplay widget. 

Lines 38-40 Since this mode uses the same widget as the display mode, it will need to 
define components for each of the same zones. Since we want to display the 
same components, these zone definitions are the same as the display mode's 
zone definitions. Note that the zones for each component mode do not need to 
match, but we have done this because we have a very simple component. 
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Lines 41-45 Bindings are repeated for every component mode. This is because the 

component mode may use entirely different widgets and components, and it may 
need entirely different bindings. 



Now that the modes of our component are defined, we will want to define how 
the component switches from one mode to another. This is done by associating 
a state diagram with this component. 



48 <ktp: stateDiagram name = "Weather " /> 

49 </ktp:componentType> 

Line 48 The stateDiagram named "Weather" is associated with this component. When 

the state manager receives requests generated by an instance of this 
component, those requests will first be evaluated against the Weather state 
diagram. 

1 .1 6.3 Weather Component State Diagram 

Each component may have one state diagram associated with it. If a component 
does not have a state diagram, the component does not handle any events. 

The weather component uses a state diagram named "Weather". The Weather 
state diagram is defined in the state diagram file "Weather.ksd". 

The new state diagram tag <ktp:componentState> is the component equivalent 
of a displayState. When a component ends up in a componentState, the state 
manager sets its mode to the name of the componentState. In this way, a 
componentState has a one-to-one relationship to component modes defined in 
the KApp file. 

1 <?xml version=* 1 . 0" ?> 

2 <!DOCTYPE ktp : stateDiagram SYSTEM "http://www.kinzan.net/dtd/ksd.dtd"> 

3 <ktp: stateDiagram name=" Weather" startState= "display" 
xmlns:ktp="http: //www. kinzan.net"> 

<!--if an action throws an exception it may be caught by a <ktp:catch> statement- -> 

4 <ktp : catch exception^ "net . kinzan .state . action . InvalidParameterException" 

5 state="display"/> 

6 <ktp: componentState name= "display" > 

7 <ktp: transition event=" Forecast" state="xSetForecast" /> 

8 <ktp: transition event="Go" state="xSetDetail " /> 

9 </ ktp: components tate> 

10 <ktp: componentState name= " f orecastDisplay" permissions forecast" > 

11 <ktp: transition event="Detail" state-"xSetDetail " /> 
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12 <kcp: transition event="Go" state="xSetForecast" /> 

13 </ktp: componentState> 

Lines 1 -2 XML file headers define the file type. 

Lines 4-5 A catch statement. Rather than coding to the FAILURE event (of KTP 3), the 
actual exception thrown by an Action can be caught. The catch is similar to a 
state transition since it defines a result state when the exception is caught. 

Lines 6-9 The component mode "display" is represented in the state diagram. From the 
display mode, two transitions may occur. The "Forecast" event will trigger a 
transition into the "xSetForecast" Action (described later). The "Go" event will 
trigger a transition into the "xSetDetail" Action (also described later). 

Lines 10-13 The component mode "forecastDisplay" is represented in the state diagram. It 
has two transitions. 



The Actions (formerly PipelineComponents) required for the Weather Component 
are simple and were therefore coded as inline JavaScript. 

14 <ktp:actionState name= "xSetForecast " permissions" forecast " > 

15 <ktp: script language=" JavaScript "> 

16 zipcode = actionEvent .getAttribute( "zip" ); 

17 userContext. setAttribute ( "zip", zipcode ); 

18 userContext. setAttribute ( "url", "http://209.70.191.lll/forecast/" 

19 + zipcode. substring ( 0, 1 ) + "/" + zipcode + ".gif" ); 

20 actionEvent . setName ( "SetForecast " ); 

21 </ktp: script> 

22 <ktp: transition event=" SetForecast" state=" forecastDisplay" /> 

23 </ktp:actionState> 

24 <ktp:actionState name=" xSetDetail "> 

25 <ktp: script language=" JavaScript -> 

26 zipcode = actionEvent .getAttribute ( "zip" ); 

27 userContext. setAttribute ( "zip", zipcode ); 

28 userContext . setAttribute ( "url " , "http: //209 . 70 . 191 . 111/zipcode/ " 

29 + zipcode. substring ( 0, 1 ) + "/" + zipcode + ".gif" ); 

30 actionEvent .setName ( "SetDetail" ); 

31 </ktp:script> 

32 <ktp: transition event= "SetDetail " state="display" /> 

33 </ktp:actionState> 

Line 14 Defines an ActionState named "xSetForecast". The State requires the 
permission named "forecast" in order to be executed. 

Lines 15-21 Defines an inline JavaScript definition for this component. This is the server side 
code that will be executed when this state is entered. Alternatively an Action 

Class (a Java Class that implements the net . kinzan . state . action . Action 

interface) could be defined for the ActionState. 

Line 22 A transition for the "SetForecast" event is defined. The ActionState returns this 

event when it has set the forecast information. 
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Lines 23-33 The xSetDetail ActionState is defined in much the same way as the xSetForecast 
was. 

file: weather. kapp 

<?xml version=" 1 . 0" ?> 

<!DOCTYPE ktp:kapp SYSTEM "http :/ /www. Jcinzan.net /dtd/kapp.d td" > 

<ktp:kapp name = "weather" xmlns : ktp=" http: //www. kinzan.net "> 

<!-- Define domains --> 
<ktp :domainList> 

<ktp:domain name= M localhost" do cumentRoot= "weather H /> 
< / ktp : domainLi s t> 

<!-- Includes --> 
<ktp : includeList> 

<ktp: include>simplegui . kapp</ktp : include> 

<ktp : include>assetlib. kapp</ktp: include> 

< ktp : inc lude> log in . kapp< / ktp : inc lude> 
</ktp: includeList> 

< ! -- Widgets - - > 
<ktp : widgetList> 

<ktp: widget name="WeatherDisplay"> 

<ktp:attributeList> 

<ktp:local name=" title" type=" java . lang. String" def aultValue=" Weather " /> 
<ktp: local name = "prompt" type=" java. lang. String" defaultValue=" Enter Zip:"/> 
< ktp: local name=" submitValuel" type=" java. lang . String" defaultValue="Go* /> 
<ktp: local name=" submitValue2 " type=" java. lang. String" /> 

</ktp:attrxbuteList> 

<ktp:widgetAssetList> 

<ktp: widgetAsset name="Go" asset="GoButton" overwriteable= " true" /> 
< /ktp: widget As setList> 

<ktp:widgetTemplate style= M false" 
locale= H false ">wea therDisplayTemplate. kwt< /ktp: widgetTemplate> 

</ktp:widget> 

</ktp:widgetList> 

< ktp : componentTypeLi s t> 

<!-- The component name must be unique within this site --> 
<ktp:componentType name= "Weather" defaultMode=" display "> 

<ktp:description>This is a very simple weather widget</ktp:description> 

<ktp:attributeList> 

<ktp: reference name=" title" widget="WeatherDisplay" attribute^" title" /> 
</ktp:attributeList> 

<ktp : componentList> 

<ktp: component name=" weather Image" type = "URL Image " /> 

<ktp: component name="ziplnput" type="TextBox" /> 

<ktp: component ref erence= "myLogin" /> 
</ktp: componentList> 
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<ktp : componentModeList> 

<kcp: componencMode name= "display" widgets "WeatherDisplay"> 

<ktp:zone names "weacherlnf o" components "weather Image" /> 
<ktp:zone name=" inputArea" components "zipinput" /> 
<ktp:zone names" ioginZone" components "myLogin" /> 
<ktp: bindings> 

<ktp: binding component =" weather Image" attributes "URL" 
defaultValue="http: //209 .70. 191 . lll/zipcode/9 /90210 .gif "> 
<ktp:from userContext= "ur 1 " /> 
</ktp:binding> 

<ktp:binding component =" weather Image" attribute="width"> 

<ktp:from literal="150"/> 
</ktp:binding> 

<ktp:binding components "weather Image" attribute="height "> 

<ktp:from literals-'SO" /> 
</ktp:binding> 

<ktp:binding components "ziplnput" attributes-value" defaultValue="90210"> 

<ktp:from userContexts " zip" /> 
</ktp:binding> 



<ktp: binding components ziplnput" attributes" size" > 

<ktp:from literals" 7 "/> 
</ktp:binding> 

<ktp: binding components "ziplnput" attributes "name "> 

<ktp:from literal= " zip" /> 
</ktp:binding> 

<ktp : binding widgetAttribute= " submi tValue2 "> 

<ktp:from literal=" Forecast "/> 
</ktp:binding> 

<ktp : binding widgetAt tributes "prompt " > 

<ktp: from bundles" com. kinzan . example . weather . Weather_res " 
attributes "ENTER_Z IP" /> 

</ktp : binding> 

<ktp:binding attributes - title " > 

<ktp: from bundle=" com. kinzan . example .weather . Weather_res " 
attributes -TITLE" /> 

</ktp:binding> 
< /ktp : bindings> 
< / ktp : componentMode> 

<ktp:componentMode names- forecastDisplay" widget="WeatherDisplay"> 
<ktp:zone names "weather Info" components "weather Image " /> 
<ktp:zone names- inputArea" components - zip Input ■ /> 
< ktp: zone names- IoginZone" components "myLogin" /> 
<ktp : bindings> 

<ktp:binding components "weather Image" attributes "URL" 
defaultValue="http: //209. 70. 191. Ill /forecast /9/90210. gif "> 
<ktp:from userContexts-url" /> 
</ktp:binding> 

<ktp:binding component =" weather Image" attributes"width"> 
<ktp:from literals ■ 396 " /> 
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</ktp:binding> 

<ktp: binding component=" weather Image" attribute=" height "> 

<ktp:from literal="176"/> 
</ktp:binding> 

<ktp:binding component= " ziplnput " attribute^ value" defaultValue= u 90210"> 

<ktp:from userContext= ■ zip" /> 
</ktp:binding> 

<)ctp: binding component = "ziplnput 1 * attribute^' name "> 

<ktp:from literal="zip" /> 
</ktp: binding> 

<Jctp: binding components ziplnput" attribute="size"> 

<ktp:from li teral= " 7 - /> 
</ktp:binding> 

<ktp: binding widgetAttribute="submitValue2 "> 

<ktp:from literal="Detail" /> 
</ktp :binding> 

<ktp : binding widgetAttribute= "prompt " > 

<ktp : from bundle= " com . kinzan . example . weather . Weather_res " 
attribute="ENTER_ZIP" /> 

</ktp:binding> 

<ktp:binding attribute= ■ title" > 

<ktp : from bundle= " com . kinzan . example . weather . Weather_res " 
attribute= "TITLE" /> 

</ktp: binding> 
</ktp :bindings> 
< / ktp : componentMode> 

< / ktp : componentModeLis t> 

<ktp:stateDiagram name= "Weather " /> 

</ktp: componentType> 

< /ktp: component TypeList> 



<ktp:KPDList> 

<ktp:KPD name=" f irstComponent " title="FirstComponent"> 
<ktp:description>My first components ktp : description 
<ktp: component name="weatherComponent " type =" Weather" 
uniqueName=" examples .weather" / > 
</ktp:KPD> 
</ktp:KPDList> 



</ktp:kapp> 

end of file: weather. kapp 
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file: wea ther Display? emplat e. kwt 

<table> 
<tr> 

<td> 

<ktp:text text="widget . title" /> 
</td> 
</tr> 
<tr> 

<td> 

<ktp:zone name= M weatherInfo" /> 
</td> 
</tr> 



<tr> 

<td> 

<ktp: form> 

<ktp:text text= "widget .prompt" /> 
<ktp:zone name= " inputArea" /> 

<ktp: submit value= "widget . submitValuel " image= "widget .Go" /> 
<ktp: submit value = "widget . submitValue2 ■ /> 
</ktp : f orm> 
</td> 
</tr> 



</table> 
<table> 
<tr> 

<td> 

<ktp:zone name= " loginZone" /> 
</td> 
</tr> 
</table> 



end of file: weatherDisplayTemplate . kwt 



1.17 KApp requirerner^ 

' security. 'l^.-^ffl^MSt^m^-'':/Oi^& 

The weather component has a protected mode. To allow access to application 
users we will need to map the component instance with the component 
permission required to access it. This requirement means we have to give the 
component a site-wide unique name using the uniqueName attribute. 

<ktp:kapp name = "weather" xmlns : ktp="http: //www. kinzan.net"> 

3 <ktp:KPDList> 

4 <ktp:KPD name=" f irstComponent" title=" FirstComponent"> 

5 <ktp:description>My first component</ktp :description> 

6 <ktp: component name="weatherComponent" type= "Weather " uniqueName =" examples. weather 

7 </ktp:KPD> 

8 </ktp:KPDList> 
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</ktp: kapp> 



Line 6 the uniqueName attribute is added to the component instance definition so that it 

can be bound to security mappings in the KSec file. 



1.18 ComponentMode ACLs 

The weather application requires a user to have- permission to get the forecast. 
After all, not just anybody can know tomorrow's weather. To enforce this 
requirement we must add permission to the forecast mode. To be quite secure, 
we will protect both the forecast actionState that transitions to the forecast 
displayState and the displayState itself. 



This is to safeguard future changes where a new transition may be added to the 
displayState bypassing the actionState. 

<ktp:stateDiagram name = "Weather" startState="display" xmlns : ktp="http: / /www. kinzan. net u > 



9 <ktp: components tate name= M forecast Display" permissions "forecast" > 

10 <ktp: transition event=" Detail" state="xSetDetail" /> 

11 <ktp: transition event= n Go" state="xSetForecast " /> 

12 </ktp : componentState> 

13 <ktp: actionState name="xSetForecast" permissions -forecast" > 

14 <ktp:script language= B JavaScript "> 

zipcode = actionEvent .getAt tribute ( "zip" ); 
userContext . setAttribute { "zip", zipcode ); 

userContext.setAttribute< "url" , "http://209.70.191.lll/forecast/" 
+ zipcode. substring ( 0, 1 ) + "/" + zipcode + ".gif" ); 
actionEvent.setName( "SetForecast" ) ,- 

15 </ktp:script> 

<ktp: transition event="SetForecast " state=" f orecastDisplay" /> 

16 </ktp:actionState> 

</ktp: stateDiagram> 

Line 9 Permission attribute is added to forecast displayState - the attribute value is the 

action name of the permission that will be checked at runtime. 

Line 13 Permission attribute is added to forecast actionState 

1 .19 Dealing with Security ^ Vkiy^fl 

The Kinzan platform deals with security transitions through exceptions. 

There are 3 main exceptions to consider in your application KSD file: 
• javax.security.auth.login.FailedLoginException 
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User is either not logged in or cannot be logged in (bad username/password) 
net.kinzan.security.auth.NoAuthorityException 

User is logged in but lacks necessary permissions - 2 possible ways to 
handle this is to offer the user a chance to logout and re-login as a user with 
correct privileges or to politely inform the user they have attempted an action 
they are not authorized to make. 

javax.security.auth. login. LoginException 

Parent exception to all login exceptions including the previous 2 exceptions 

To forward a user to a security login page use ksd LoginWizard state 
LoginDisplay and they will be forwarded to a Login KPD with the login 
component as the root component giving the user a chance to login to the 
application. Remember that the StateManager goes from top to bottom in 
matching an exception to transition. So be sure to have the first 2 exceptions 
listed above listed before the 3 rd one. 



<ktp:stateDiagram name= "Application" startState= "one" xmlns : ktp="http: / /www. ki nzan.net'"> 

1 <!-- User Failed to Login --> 

2 <ktp: catch exceptions javax. security . auth. login. FailedLoginExcept ion" state=" 
LoginDisplay" wizard= " LoginWizard" /> 



3 


<!--l 


- -> 




4 


<ktp 


5 


< ! -- 


6 


<ktp 


7 


<ktp 


3 


<ktp 


9 


<ktp 



</ktp: stateDiagram> 



Lin e 2 Catch the bad password and redisplay the LoginWizard LoginDisplay state 

Line 4 Catch the NoAuthority exception and move to NoAuthority state which will just 

print out an HTML file with an explaination of the error. 

Line 6 Catch the general LoginException and send to an error page. 

1.20 Application Security (KSec) 



For the weather example, we need to supply a Kinzan Security (KSec) file to map 
component permissions to application roles. We have two significant roles to 
point out. "ADMIN" is any application admin user that will be granted any 
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permission required by weather component, whereas the "USER" application role 
will only be granted "forecast" permission. 



1 <ktp:ksec name = "weather " xmlns : ktp=" http : / /www. kinzan.net "> 

2 <!-- 

3 Application Roles 

4 List all roles available in this site to users 

5 Assign to each role the component access permissions granted to the role 

6 --> 

7 <ktp:appRole> 

8 <ktp:role name= " SUPER " > 

9 <!-- allaccess grants all necessary permissions to use everything 

10 <!-- convenient shorthand — > 

11 <ktp :componentAccess allaccess=*true" /> 

12 </ktp:role> 

13 <ktp:role name = "ADMIN "> 

14 <!-- component permissions can either be spelled out or set attribute 

15 allpermission to true this is an example of the allpermission case 

16 --> 

17 <ktp:componentPermission componentUniqueName=* examples .weather" allpermission="true" 

18 </ktp:role> 

19 <ktp:role name="USER"> 

20 <! — component permissions can either be spelled out or set attribute allpermission 

21 to true this is an example of listing permissions 

22 --> 

23 <ktp: component Permission componentUniqueName= " examples .weather" > 

24 <ktp:permission name=" forecast " /> 

25 </ktp:componentPermission> 

26 </ktp:role> 

27 <!-- Default to All Users --> 

28 <ktp:role> 

29 </ktp:role> 

30 </ktp:appRole> 

31 </ktp:ksec> 



is a site wide super permission that encompasses all permissions necessary for 
access - equivalent of root on UNIX and administrator on NT but only as far as 
the application is concerned. 

grant all permissions for a specific component instance to the encapsulating role 
in this case it is the "ADMIN" role 

A specific named permission on a component instance is granted. In this case, 
forecast permission is granted to "USER" role. 



Line 11 

Line 17 
Lines 23-25 
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file: Weather. ksd 

<?xml version=" 1 . 0"?> 



<!DOCTYPE ktp:stateDiagram SYSTEM "http : / /www. kinzan. net/dtd/ksd.dtd"> 

<ktp:stateDiagram name = "Weather " startState="display" xmlns : ktp="http: / /www. kinzan. net" > 

<!-- if an action throws an exception it may be caught by a <ktp:catch> statement --> 
<ktp: catch exception= u net .kinzan. state .action. InvalidParameterException" 
state=" display" /> 

<ktp: components tate name = "display" > 

<ktp: transition event=" Forecast " state="xSetForecast" /> 
<ktp: transition event="Go" state= "xSetDetail" /> 
< / ktp : components tate> 

<ktp:componentState name=" f orecastDisplay" permission^" forecast" > 

<ktp: transition event=" Detail " state="xSetDetail " /> 

<ktp: transition event="Go" state= "xSetForecast " /> 
</ktp:componentState> 

<ktp:actionState name= "xSetForecast" permissions forecast" > 
<ktp : script language= "JavaScript " > 

zipcode = actionEvent .getAt tribute ( "zip" ); 
userContext.setAttribute( "zip", zipcode ); 

userContext.setAttribute( "url", "http://209.70.191.lll/forecast/- + 
zipcode. substring ( 0, 1 ) + "/* + zipcode + ".gif" ); 

actionEvent. setName ( "SetForecast" ); 
</ktp: script> 

<ktp: transition event=" SetForecast " state=" f orecastDisplay" /> 
</ktp:actionState> 

<ktp : act ionS tate name= " xSetDetai 1 " > 
<ktp : script languages "JavaScript " > 

zipcode = actionEvent .getAttribute ( "zip" ); 
userContext . setAttribute ( "zip", zipcode ); 

userContext . setAttribute ( "url", "http : / /209 . 70 . 191 . 111/zipcode/ ■ + 
zipcode. substring! 0, 1 ) + "/" + zipcode + ".gif" ); 

actionEvent . setName ( "SetDetail" ); 
</ktp:script> 

<ktp: transition event=" SetDetail" state="display" /> 
< /ktp: actions tate> 



</ktp:stateDiagram> 
end of file: Weather. ksd 
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4. Stock Quote Component 

1.21 Introduction 



1.21.1 Audience 

This document is intended for developers who will be working with the Kinzan 
Technology Platform. It explains some aspects of the KTP 4 component 
architecture by walking through an example component. This document 
assumes that the reader has reviewed the weather component document 
(above) and understands the terms described therein. 



1 .21 .2 Overview 

This document describes a sample Kinzan component-the stockquote 
component. The stockquote component gives a listing of current stock quotes in 
a generic table widget. The stock quotes are bound from an EJB, obtained 
through a business rule (session bean), an aspect of the platform not utilized by 
the weather component. 

1 .22 stbcipa^ 

The stockquote component is defined in a KApp file named stockquote.kapp. 
We will walk through the important elements of stockquote.kapp and see what 
they do. 

1 .22.1 Stockquote Widget Definition 

The first important piece of the stockquote KApp file is the widget definition. A 
widget is a view. It is completely independent from the data it displays. It may 
have multiple representations based on device and locale. 



1 <ktp:widget name="StockDisplay"> 

2 
3 
4 
5 
6 

7 
8 



<ktp:attributeList> 

<ktp: local name= "prompt" type=" java. lang. String" /> 
</ktp:attributeList> 

<ktp:widgetTemplate style=" false" 

locale=" false"> 
StockDisplayTemplate . kwt 
< /ktp : widgetTemplate> 
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9 </ktp: widget> 

Line 1 The widget is defined with the name "StockDisplay" 

Lines 2-4 The attributes of the widget are defined and given default values. The attributes 
are defined in order that a component definition can bind particular values to 
them. Each of these attribute names corresponds to a template variable with the 
name ,, widget.<attributeName>". The widget template, 

"stockDisplayTemplate.kwT, is included at the end of this document. Look at that 
and compare its contents with this segment of the kapp file. 

Lines 6-8 The widget template. This points to the widget template file. There are no style 
or locale variants for this widget. However, there are device variants. 

The stockquote component makes use of a generic table widget to display its 
stock data. This widget and its associated generic component are defined in a 
KApp file included into the stockquote.kapp file. Please refer to the explanation of 
the GenericDataTable Component for details of its associated attributes. 



1 .22.2 Stock Quote Component Definition 

As with the weather component, the stock quote component utilizes one main 
widget to present its view to the user. The widget "StockDisplay" contains the 
templates for each device supported by this component. Adding a device 
variation only requires adding the appropriate device variant templates to the 
widgets involved. The component itself is separated from the view and does not 
need to be aware of the actual view rendered. The StockDisplay widget includes 
zones that are mapped to other components containing other presentation 
elements. The stockquote component only contains one mode, which uses the 
StockDisplay widget. 



1 <ktp:componentType name="StockQuote" defaultMode=" display" > 

2 <ktp:description>This is a stock quote component</ktp: description 

3 <ktp:attributeList> 

4 <ktp: local name=" title" 

type= " j ava . lang . String " 
defaul tValue=" Stocks " /> 

5 <ktp: local name = "defaul t Symbols " 

type=" java. lang. String" 

def aultValue=" A DJI, ^IXIC, ~XAX" /> 

6 <ktp: local name="dataType" 

type=" java. lang. String " 

defaul tValue=" symbol , price, change, date" /> 
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</ktp:attributeList> 



8 <ktp:componentList> 

9 <ktp: component name =" symbol Input " type= "TextBox" /> 

10 <ktp : component name=" da taDi splay " 

type =" Generic Da taTable" 
style=" stocktable" /> 

11 </ktp : componentList> 



Line 1 The component type "stockquote" is defined. It has a default mode named 

"display". 

Line 2 The component description. This does not affect the rendering system. 

Lines 3-7 The component has three attributes. Each attribute is local to the component 
and contain default values. 

Lines 8-1 1 Lists the child components used by this component. Each child component is 

local to this component. The "GenericDataTable" component is the generic table 
component while the "TextBox" component is the same component type used by 
the weather component for a simple text input field. 



Differing from the weather component, the stockquote component has another 
section in its definition to list the model beans that will be used by this component 
to obtain the stock quote data. 

12 <ktp:modelBeanList> 

13 <ktp: model Bean name="StockSymbols"> 

14 <ktp:rule name="StockTool ,, method= tt getStockSymbols" /> 

15 <ktp:param name="paraml° 

type=" java. lang . String" 
def aultValue =" guest "> 

16 <ktp:from userContext="accountID" /> 

17 </ktp:param> 

18 <ktp:param name="param2 " type=" java . lang .Vector "> 

19 <ktp:from attribute="defaultSymbols" 

trans formations net .kinzan. rendering. runtime. trans forma t ion. StringToVector" /> 

20 </ktp:param> 

21 <ktp:param name =" par am3" type= " java . lang . String" def aultValue="SUNW"> 

22 <ktp:from userContext= "net . kinzan. stockquote .cur rent Symbol " /> 

23 </ktp:param> 

24 </ktp:modelBean> 

25 <ktp: model Bean naLme="StockData"> 

26 <ktp:rule name="StockQuote" method= "getStockQuotes" /> 

27 <ktp:param name= "paraml " type=" java .util .Vector "> 

28 <ktp:from modelBean="StockSymbols" /> 

29 </ktp:param> 

30 <ktp:param name="param2 " type=" java .util .Vector" > 

31 <ktp:from attribute="dataType" 

transf ormation=- net. kinzan. rendering. runtime. trans formation. StringToVector •/> 
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32 </ktp:param> 

33 </ktp :modelBean> 

34 </ktp:modelBeanList> 



Line 13 A model bean is defined by the name "StockSymbols". This name is the name 

that the rest of the component definition can refer to this model bean by. 

Lines 14 A model bean is returned by calling a specific method in a business rule, as 
defined in this line. The business rule needs to be registered with a bean 
manager in the system. The bean managers that this KApp requires are listed at 
the top of the KApp file. 

Lines 15-23 These lines define the parameters to pass to the business rule method defined in 
line 14 in order to generate the required model bean correctly. The parameters 
must be listed in the order that the interface to the business rule method is 
defined. 

Line 19 This parameter definition is of note because it contains a transformation attribute, 

which defines a class that the component service will utilize to transform the input 
type of the "defaultSymbols" attribute of the component to a Vector, which is the 
type that the business rule expects for this parameter. 

Lines 24-33 These lines define another model used by the stockquote component, 

"StockData". Note that as one parameter to the business rule, the entire 
"StockSymbols" model bean is passed. This dependency is resolved by the 
component service, in that it only instantiates model beans as needed. This will 
work as long as there are no cyclic references. 



There is one more item worth mentioning concerning the model beans. In our 
implementation, the "StockSymbols" bean and "StockTool" business rule are 
deployed remotely and managed by the RemoteEJBBeanManager, while the 
"StockData" bean and "StockQuote" business rule are deployed locally in the 
platform's build in EJB container and managed by the LocalEJBBeanManager. 
Despite this, their definition is the same, and the component utilizes them in the 
same way. 

Now that we have defined the model beans, child components, and attributes, we 
are ready to define the stock quote component's one mode, "display". Since we 
have reviewed bindings in the weather component, we will only highlight the 
different details of the stock quote's mode definition. 



34 <ktp:componentModeList> 

35 <ktp:componentMode name= "display" widget= "StockDisplay"> 

36 <ktp:zone name=" inputArea" component= "symbol Input " /> 
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37 <ktp:zone name= n displayArea" component="dataDisplay" /> 

38 <ktp : bindings> 



39 <ktp: binding component=" da taDi splay" attributes "content "> 

40 <ktp:from modelBean= " StockData " /> 

41 </ktp:binding> 

42 <ktp: binding component= M dataDisplay" attributes "header "> 

43 <ktp:from literal=" Symbol, Price, Change, Date " 
trans f ormation= "net . kinzan . rendering . runtime . transformation . StringToVector " / > 

44 </ktp:binding> 



45 </ktp:bindings> 
4 6 </ktp : componentMode> 

47 </ktp:componentModeList> 

48 <ktp: stateDiagram name="Stockquote" /> 

49 </ktp: componentType> 

Line 35 The display mode of the component is defined. It uses the StockDisplay 

widget. 

Lines 36-37 The zone mappings for this component. 

Lines 39-40 The binding to the content attribute of the dataDispiay component is the 
stockData model bean. 

Lines 42-44 The binding to the header attribute of the dataDispiay component is from a string 
literal. However, the attribute is a Vector, so a transformation is applied. 

Line 48 The state diagram for the stock quote component is defined here. 



1 .22.3 Stock Quote Component State Diagram 

Like the weather component, the stock quote component utilizes a state diagram 
to define the application flow and business logic. The stock quote state diagram 
is fairly simple, since it needs only to set the current requested symbols in the 
user context and allow the component bindings and model beans to retrieve the 
required quotes and display them through the widgets. 

<ktp: stateDiagram name="Stockquote" startState="display" 
xmlns :ktp="http: / /www. kinzan . net "> 

<ktp:catch exceptions java. lang. Exception" state="display" /> 
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3 <ktp:componentState name= H dispiay"> 

4 <ktp: transition event="Go" state="xSet Symbol" /> 

5 </ktp: components tate> 



6 <ktp:actionState name = "xSet Symbol "> 

7 <ktp: script language = "JavaScript ** > 

8 symbol = actionEvenc .getAttribute ( "symbol" ); 

9 userContext . setAttribute ( "net . kinzan . stockquote . cur rent Symbol" , symbol ); 

10 actionEvent . setName { "SetSymbol" ); 

11 </ktp : script> 

12 <ktp : transition event =" SetSymbol " state="display " /> 

13 </ktp:actionState> 

14 </ktp: stateDiagram> 



Line 1 The state diagram definition. Note that the name is the same name referenced in 

the component. 

Line 2 A catch statement. Rather than coding to the FAILURE event (of KTP 3), the 

actual exception thrown by an Action can be caught. The catch is similar to a 
state transition since it defines a result state when the exception is caught. 

Lines 3-5 The component mode "display" is represented in the state diagram. Only one 
event is supported, the "Go" event, which will cause the transition to the 
"xSetSymbol" state. 

Lines 6-13 The component mode "xSetSymbol", an action state written in JavaScript that 
takes the symbol input and places it into the user context. 



1 .22.4 Device Variations 

The stockquote component supports variants in HTML and WML. This is 
achieved by defining the appropriate variant templates for each of the widgets 
utilized in rendering the display for the component. The remainder of the 
component definition is independent of the view, and thus it is independent of the 
device that it will ultimately be displayed on. 

An advantage of using pre-built GUI widgets, such as the Generic Table widget, 
is that the component you are building will automatically have support for 
whatever devices and to some extent, styles and locales, that the widget 
supports, as long as the other widgets and components your component utilizes 
also offer the same support. If a certain variant is not supported, a new template 
variant would be required, but the bindings and attributes for the component 
definition remain unchanged. 
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The WML variant for the stockquotedisplay widget is listed below. 

file: stockquote . kapp 

<?xxnl version="1.0"?> 

<!DOCTYPE ktp: kapp SYSTEM "http://www.lcinzan.nec/dtd/kapp.dtd" > 

<ktp:kapp name="stockquote" xmlns : ktp="http: //www. kinzan.net "> 

<!-- domains - - > 
<ktp:domainList> 

<ktp: domain name= " local host " documentRoot="stockquote" /> 
< /ktp : domainList> 

<ktp : beanManagerLis t> 

<ktp:beanManager name="kinzan: /beanmanager/kinzan/LocalEJBContainer " /> 
<ktp:beanManager name="kinzan: /beanmanager/kinzan/RemoteEJBContainer" /> 

< /ktp: beanManagerLis t> 

<!-- Includes --> 
<ktp: includeLiso 

<ktp: include>simplegui .kapp</ktp: include> 

<ktp: include>genericdatatable. kapp</ktp: include> 
</ktp: includeList> 

<! — Styles --> 
<ktp: styleList> 

<ktp: style najne=" stock table" file="stocktable. style "> 

<ktp:description>Styles for the stock table</ktp:description> 

</ktp:style> 
</ktp:styleList> 

<!-- Widgets - -> 
<ktp: widget Lis t> 

<ktp: widget name= H StockDisplay"> 

<ktp:attributeList> 

<ktp: local name=" prompt" type=" java . lang. String" /> 
</ktp:attributeList> 

<ktp : widgetTemplate style= " false " 

locale=" false"> 
StockDisplayTemplate . kwt 
</ktp: widgetTemplate> 

</ktp:widget> 

</ktp:widgetList> 

<ktp : componentTypeLi s t> 

<!-- The component name must be unique within this site — > 
<ktp:componentType name="StockQuote" defaultMode=" display" > 

<ktp:description>This is a stock quote component</ktp: description 

<ktp:attributeList> 

<ktp: local name="title" 

type=" java. lang. String" 
defaultValue=" Stocks "/> 
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<kcp: local name="defaultSymbols" 
cype=" java . lang. String" 
defaultValue="' v DJI , ~IXIC, ~XAX" /> 

<ktp: local name="dataType" 

cype=" java . lang . String- 
default Value =" symbol , price, change, date" /> 

</ktp:attributeList> 

<ktp: componentList> 

<ktp : component name= " symbol Input " type="TextBox" /> 
<ktp: component name= "da taDi splay" 

type= " Gener ic Da taTable " 
style= n stocktable"/> 
< / ktp : componentLis t> 

<ktp:modelBeanList> 

<ktp:modelBean name ="S toe kSymbols'*> 

<ktp:rule name="StockTool" method= M getStockSymbols M /> 
<ktp:param name="paraml" 

type= M java. lang . String" 
defaultValue= "guest "> 
<ktp: from userContext="accountID" /> 
</ktp:param> 

<ktp:param name="param2" type=" java. lang. Vector "> 
<ktp: from attribute= tt defaultSymbols" 
transf ormation=" net . kinzan. rendering, runtime, trans formation. StringToVector" /> 
</ktp:param> 

<ktp:param name= "param3 " type=" java. lang. String" def aultValue="SUNW"> 

<ktp: from userContext="net .kinzan.stockquote.currentSymbol" /> 
</ktp:param> 
< / ktp : mode 1 Bean> 

<ktp:modelBean name="StockData"> 

<ktp:rule name='*StockQuote" method="getStockQuotes" /> 
<ktp:param name= "paraml " type= M java. util. Vector "> 

<ktp : from modelBean= "StockSymbols B /> 
</ktp:param> 

<ktp:param name= "param2 " type=" java. util .Vector "> 
<ktp:from attribute= "dataType" 
transformation^ "net . kinzan. rendering . runtime . t rans format ion. StringToVec tor " /> 
</ktp:param> 
</ktp:modelBean> 

</ ktp : modelBeanLis t> 

<ktp : componentModeList> 

<ktp: componentMode name=" display" widget="StockDisplay"> 
<ktp:zone name=" inputArea" component= "symbol Input " /> 
<ktp:zone name="displayArea" component =" da taDisplay"/> 
<ktp :bindings> 

<ktp : binding widgetAttribute= "prompt " > 

<ktp:from literal="Symbol: "/> 
< / ktp : binding> 

<ktp: binding component ="symbolInput" 

attribute="value" defaultValue=" "> 
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<ktp : from userConcexc="nec . kinzan. scocJcquote .current Symbol" /> 
</ktp:binding> 

<ktp: binding components" symbol Input" attribute="size"> 

<ktp:from literals'* 5 " /> 
</ktp:binding> 

<ktp:binding components "symbol Input" attribute= "name"> 

<ktp:from literal=" symbol " /> 
</ktp:binding> 

<ktp: binding components "dataDisplay" attribute= "content" > 

<ktp: from modelBean="StockData" /> 
</ktp:binding> 

<ktp: binding components "dataDisplay" attributes "header "> 
<ktp: from literals" Symbol, Price, Change, Date" 
trans formations "net .kinzan. rendering. runtime. trans forma tion.S tringToVector " /> 

</ktp:binding> 

<ktp: binding components "dataDisplay" attributes- footer "> 
<ktp : from 1 i teral = " Symbol , Price , Change , Date " 
transf ormation= "net .kinzan. rendering. runtime. transformation. StringToVector" /> 

</ktp:binding> 

<ktp : binding components "dataDisplay" 

at tribute= "defaults tyleClass "> 
<ktp: f rom literals" DefaultTable" /> 
< /ktp : binding> 

<ktp: binding components "dataDisplay 1 * attributes "rowClasses"> 
<ktp: f rom li teral = "GrayTR, WhiteTR,GrayTR, WhiteTR" 
trans formations "net . kinzan . rendering . runtime . trans formation . S tringToVector " /> 

< /ktp : binding> 

<ktp: binding components -dataDisplay" attributes "headerClasses"> 
<ktp:from literals "HeaderBar " 
transf ormation="net . kinzan. rendering . runtime . trans format ion. S tringToVector " /> 

< / ktp : binding> 

<ktp: binding components "dataDisplay" attributes" da taTypes"> 
<ktp: from 

li teral=" symbol , price, price_inc ,price_dec, price_unc" 

transf ormation=" net .kinzan. rendering. runtime. trans forma tion.S tringToVector " /> 

</ktp:binding> 

<ktp: binding components "dataDisplay" attributes" da taTypeClass"> 
<ktp : from 

literals " StockSymbol , StockPrice , Pricelnc , PriceDec , PriceUnc " 

transf ormations "net . kinzan . rendering . runtime . transformation . S tringToVector " /> 

</ktp:binding> 

<ktp: binding components "dataDisplay" attributes "dataTypeReplace"> 
<ktp : from literals » , , , , Unchanged" 
trans formations « net . kinzan . rendering . runtime . trans formation . S tringToVector ■ /> 

</ktp:binding> 

< /ktp : bindings> 

< / ktp : componentMode> 

< / ktp : component ModeL is t> 

<ktp: stateDiagram names - stockquote " /> 

< / ktp : componentType> 

</ktp: componentTypeList> 



<ktp:KPDList> 
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<ktp:KPD name=" Stock Page" title="Stocks ! "> 

<ktp:descripcion>A Stock page</ktp: description 

<ktp: component name= "myStockComponent " type= " StockQuote" /> 

</ktp:KPD> 
</ktp:KPDList> 



</ktp:kapp> 

end of file: stockquote . kapp 
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file: stockDisplayTemplate . kwt (html version) 

<table> 
<tr> 

<td> 

<ktp:zone name="displayArea" /> 
</td> 
</tr> 

<tr> 

<td> 

<ktp: form> 

<ktp : text text= " widget . prompt " /> 
<ktp:zone name=" input Area" /> 
<ktp: submit value="Go"/> 
</ktp: form> 
</td> 
</tr> 

</table> 

end of file: StockDisplayTemplate. kwt (html version) 
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file: stockDisplayTemplate.kwt (wml version) 

<ktp:zone name="displayArea" /> 



<p> 

<ktp: text text=" widget .prompt" /> : 
<ktp:zone name=" inputArea" /> 

</p> 

<p align="center "> 
<ktp: f orm> 

<Jctp: submit value="Go" /> 
</Jctp: f orm> 

</p> 

end of file: stockDispl&yTemplate.kwt (wml version) 
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file: stockquote.ksd 

<?xml version="l . 0"?> 



<!DOCTYPE ktp:stateDiagram SYSTEM "http: //www. kinzan.net/dtd/lcsd. dtd"> 

<ktp: stateDiagram name=" Stockquote" startState= M display" 
xmlns : ktp="http: //www. kinzan.net "> 

<ktp:catch exception=" java . lang. Exception" state="display" /> 

<ktp : componentState name= "display " > 

<ktp: transition event="Go" state=" xSetSymbol " /> 
< /ktp : components tate> 



<ktp:actionState name="xSetSymbol ,, > 

<ktp: script language= u JavaScript "> 

symbol = actionEvent . getAttribute ( "symbol" }; 

userContext . setAttribute ( "net . kinzan. stockquote . currentSymbol " , symbol ); 

actionEvent. setName( "SetSymbol" ); 
</ktp: script> 

<ktp: transition event= " SetSymbol " state= "display" /> 
</ktp:actionState> 



</ktp: stateDiagram> 

end of file: stockquote.ksd 
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S. Syndicated News Component 

1.23 Introduction 

1.23.1 Audience 



This document is intended for developers who will be working with the Kinzan 
Technology Platform. It explains some aspects of the KTP 4 component 
architecture by walking through an example component. This document 
assumes that the reader has reviewed the weather and stockquote component 
documents (above) and understands the terms described therein. 

1 .23.2 Overview 

The syndicated news component retrieves news with an EJB session bean. This 
news is then displayed with a set of widgets. The type and source of news can 
be selected from a list of news categories and feeds. The new settings for a 
configured news component are stored in the user's context. 



1124!^ 



The news component achieves all its functionality by implementing 3 modes. The 
first mode, Display, is the default mode. In this mode, the component uses a set 
of nested components to display an Edit button and a list of news items. 



B lairs key talks at Camo David 
BBCfeb 23 2001 6:30PM 

Clintons Brother Pursued Clemency Bids for Friends 
Afew York Times J^eb 23 200 1 5:38PM 

Earnhardts seat belt was broken 
Sports Network feb 23 2001 4:40PM 

Thousands flee violence in Indonesia 
USA Today J^eb 23 2001 2:57PM 

44,000 homeless in Mozambique floods 
Guardian UnlimitedSeb 23 2001 2:33PM 





jgBtey. Sflt ' yje*^ - FflYoritBs v loots ,■ 




Edit] 
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Figure 1 



When the Edit button is pressed, the news component transitions to its next 
mode, Category. In the Category mode, the component presents a drop down 
lists box where the user can select the type of news category to display. 



"3 SetonctOompooent - Mfcrosott lnt ' 



Re Eat view Favorttes Took Hefc>- 



j Ada-ess |e] http:/A>:al->ost/stace/content 



H c>Go 



Please select a new category | CONSUMER 3 
Feed I 



CONSUMER 



TECHNOLOGY 
SPORTS 
INTERNATIONAL 
FINANCE 
INTERNET 
NEWS 



Figure 2 

Once a news category is selected, the user can press the Feed button. The 
Feed button transitions the component to its third and final mode, Feed. In the 
Feed mode, the user has the opportunity to select a news feed for the previously 
selected news category. 
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Figure 3 

When a Feed is selected, the user then presses the Display button to go back to 
the Display mode. 

The next sections provides a detailed explanation of how the functionality of this 
component is achieved with the KTP. 



1 .24.1 Syndicated News Model 

The news component uses the ContentFetcher EJB bean as a business rule to 
get its content. This stateless session bean serves as a wrapper to the Content 
Service. The Content Service uses CORBA to communicate with a remote 
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Content Server. Here is the listing for the remote interface of the ContentFetcher 
bean. 



public interface ContentFetcher 
extends EJBObject, Remote 



{ 



public String [] getCategories ( ) 
throws RemoteException; 

public String [] getFeedsFromCategory ( String category ) 
throws RemoteException; 

public Articled getArticlest String category, String name) 
throws RemoteException; 



As you can see, the ContentFetcher bean provides three methods: 
getCategories, getFeedsFromCategories, and getArticles. The getCategories 
method returns an array of available news categories. The 
getFeedsFromCategory method retrieves an array of available feeds for a 
specified category. And, the getArticles method returns the news items for a 
specified category and feed. These methods will be used in the- component 
Kapp file. 

A listing for the implementation of the ContentFetcher bean is provided at the end 
of this section. This implementation assumes that the ContentFetcher bean is 
deployed in the local EJB container. 



1 .24.2 Syndicated News Widget Definitions 

The news component employs widgets to create 3 views. Each view maps to a 
component mode. The first view gets rendered when the component is in 
Display mode. This view consists of the following 3 widgets: TwoVerticalZones, 
HyperLinkableParagraph and EmptyForm. These widgets are assembled 
together to produce the view depicted in Figure 1 . 

1 <ktp: widget name="TwoVerticalZones"> 

2 <ktp:widgetTemplate style=" false" locale=" false"> 

3 twoVerticalZones.kwt 

4 </ktp:widgetTemplate> 

5 </ktp:widget> 

6 <ktp:widget name=" HyperLinkableParagraph "> 

7 <ktp:attributeList> 

8 <ktp: local naxne=* linkableParagraphList" 

9 type= " com. kinzan. widget. LinkableParagraph[ J ■/> 

10 <ktp: local name =" max Paragraphs" type=" java. lang. Integer" 

11 defaultValue='10"/> 

12 <ktp: local name="bulletGraphics" type=" java. lang. String" /> 

13 </ktp:attributeList> 
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14 <ktp: widgetTemplate scyle=" false" locale= " f alse"> 

15 hyperLinkableParagraph.kwt 

16 </ktp:widgetTemplate> 

17 </ktp:widget> 

18 <ktp: widget name = "Empty Form "> 

19 <ktp:attributeList> 

20 <ktp: local name= u event" type="java. lang. String " /> 

21 </ktp:attributeList> 

22 <ktp:widgetTemplate style=" false" locale=" f alse"> 
2 3 emptyForm . kwt 

2 5 </ktp: widgetTemplate> 

2 6 </ktp :widget> 



Lines 1-5 

Line 6 
Lines 8-9 

Lines 10-11 
Line 12 

Lines 18-26 



The TwoVerticalZones widget is defined here. The main function of this widget is 
to divide the space assigned to it into two vertical zones. The news component 
uses this widget to place the HyperLinkableParagraph widget in the top zone and 
the EmptyForm widget in the bottom zone. 

The HyperLinkableParagraph widget is defined here. This widget displays a list 
of paragraphs in a table. 

The HyperLinkableParagraph defines a linkableParagraphList attribute. This 
attribute is an array of LinkableParagraph objects. A LinkableParagraph object 
consists of a header, text, and footer. The header, text, and footer can be 
displayed as a hyperlink if a URL is associated with it. 

The number of paragraphs displayed can be controlled by setting this attribute. 

The HyperLinkableParagraph widget can also display an image at the start of 
each paragraph. This attribute can be used to specify the URL for the image. 

The EmptyForm widget provides a submit button. The label for this button can 
be customized by setting the event attribute defined in this widget. 

The second and third views (see Figures 2 and 3) are rendered by the 
DropDownListForm widget. This widget presents a list box and a submit button. 
In the Category mode, this widget is used to prompt the user for a news 
category. Moreover, in the Feed mode, the widget is used to display the available 
feeds for the chosen news category. Here is the definition for the 
DropDownListForm widget. 



27 

28 
29 
30 
31 
32 
33 



<ktp: widget name=" DropDownListForm" > 

<ktp:attributeList> 

<ktp: local name=" prompt" type=°java. lang. String" /> 

<ktp: local name='listPostName" type=" java. lang . String" /> 

<ktp:local name="listSize" type="java. lang. String" defaultValue=" 1" /> 

<ktp: local name=" options* type=" java . lang . String ()" /> 

<ktp: local name="event" type=" java . lang. String" /> 
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34 </ktp:attributeList> 

35 <ktp:widgetTemplate scyle= u false" locale=" false u > 

36 dropDownListForm. kwt 

37 </ktp:widgetTemplate> 

38 </ktp: widget> 



Line 29 The prompt attribute is the string that should be used to prompt the user. 

Line 30 The listPostName attribute is the form variable name to use when the list is 

created. 

Line 31 The listSize attribute defines the size of the list box. 

Line 32 The options attribute contains an array of strings to display in the list box. 

Line 33 The event attribute provides the string that is displayed in the submit button. 

1 .24.3 Syndicated News Component Definition 

As mentioned earlier, the first view consists of 3 widgets. To be able to assemble 
this view, a component definition is required for each widget that needs to be 
nested i.e. HyperLinkableParagraph and the EmptyForm widgets. Nesting at the 
component level results in loosely couple widgets which makes the task of 
replacing widgets much easier. Here are the component definitions for the 
EmptyForm and the HyperLinkableParagraph widgets: 

. rtar r^r^rz=zr.-„*a^; t ■ :* :•■ ■ • ■ v — urz - --Lr^?;- u r~ v irr-i ^rr.r^rtrrr-rc: ~?.t^: ^gtB^c^Ka^^^rrs^aj i^s=r :y;g& -.ritjj ^sttt^scssss^rz 

1 <ktp:componentType name=" ParagraphList" defaultMode=" display" > 

2 <ktp : description 

3 A component that contains a list of paragraphs 

4 </ktp: description 

5 <ktp:attributeList> 

6 <ktp: reference name=" linkableParagraphList" 

7 widget= "Hype rLinkable Paragraph" 

8 attributes" linkableParagraphList" /> 

9 <ktp: reference name ="maxPa rag raphs" 

10 widget =" HyperLinkableParagraph" 

11 attribute- "maxParagraphs " /> 

12 <ktp: reference name="bulletGraphics" 

13 widget=" HyperLinkableParagraph" 

14 attributes "bulletGraphic " /> 

15 </ktp:attributeList> 

16 <ktp:componentModeList> 

l" 7 <ktp:componentMode name= "display" widget= "HyperLinkableParagraph" /> 

18 </ktp:componentModeList> 

19 </ktp:componentType> 

20 <ktp: component Type name=" EmptyForm" defaultMode= "display "> 

21 <ktp:description>An empty form component</ktp : description 
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22 <ktp:attributeList> 

2 3 <ktp: reference name=" event" widget= u EmptyForm" attributed event " /> 

24 </ktp:attributeList> 

25 <ktp: componentModeList> 

2 6 <ktp:componentMode name= "display" widget= "Empty Form " /> 

27 </ktp:componentModeList> 

2 8 </ktp:componentType> 

Note that these components are very simple. They expose the widget attributes 
at the component level. They support only one mode and they do not define a 
state diagram. 

The news component can now be defined: 



29 <ktp:componentType name =" News" defaultMode="display"> 



30 



<ktp:description>This is a very simple news component</ktp : description 



31 <ktp:attributeList> 



32 <ktp: local name=" title" types" java . lang . String" def aultValue= "News" /> 

33 </ktp:attributeList> 

34 <ktp:componentList> 

35 <ktp: component name="list" type=" Paragraphias t" /> 
3 6 <ktp: component name=* , form" type=" Empty Form" /> 

37 </ktp:componentList> 



Line 29 The news component is defined here. The default mode is set to Display. 

Lines 35-36 Instances of the ParagraphList and EmptyForm components are created and 
assigned the names "list" and "form" 



The news component uses three model beans. Each model bean will be used to 
provide the data for a different mode. These model beans are generated by the 
same rule, SyndicatedContent. This rule is mapped to the ContentFetcher bean 
defined in the previous sections. Here is how all this is done in the content KApp 
file: 



38 <ktp: model Bean name =" News Articles "> 

39 <ktp:rule name =" SyndicatedContent" method="getArticles • /> 

40 <ktp:param name=" category" type= " java . lang . String" 

41 defaultValue="NEWS"> 

42 <ktp:from userContext= "category" /> 

43 </ktp:param> 

44 <ktp:param name="feed" type=" java . lang. String" 

4 5 defaultValue="TOP STORIES "> 

4 6 <ktp: from userContext=" feed" /> 
4 7 </ktp:param> 
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48 </ktp:modelBean> 

49 <ktp:modelBean name= "Category" > 

50 <ktp:rule name= u SyndicatedContent" method="getCategories" /> 

51 </ktp:modelBean> 

52 <ktp:modelBean name= " Feed" > 

53 <ktp:rule name=" SyndicatedContent" method= u getFeedsFromCategory" /> 

54 <ktp:param name=° category" type=" java. lang. String" 

55 def au It Value = "TECHNOLOGY" > 

56 <ktp: f rom userContext="category" /> 

57 </ktp:param> 

58 </ktp:modelBean> 



Lines 38-48 The NewsArticles model bean is obtained by calling the getArticles method on 

the ContentFetcher bean i.e. SyndicatedContent rule. Note that the category and 
feed parameters are taken from the user's context. 

Lines 49-51 The Category model bean is also obtained by using the SyndicatedContent rule. 
This time, we call the getCategories method. 

Lines 52-58 The Feed model contains the feeds for the provided category. The category is 
obtained from the user's context. 

The Display mode for the news component gets its contents from the 
NewsArticles model bean and displays its contents using the TwoVerticalZones 
widget and nested components. 

59 <ktp:componentMode name= "display" widge t = " Two Vertical Zones "> 

60 <ktp:zone name="top" components" list" /> 

61 <ktp:zone name =" bottom" component=" form" /> 

62 <ktp: bindings> 

63 <ktp:binding component="list" attribute=" linkableParagraphList " > 

64 <ktp:from modelBean= "NewsArticles " 

transformation="com. kinzan. example. content. transformation. ArticlesToLinkableParagraphs" /> 

65 </ktp:binding> 



66 



<ktp: binding component=" list " attributes "maxParagraphs' 



67 defaultValue="5"> 



< ktp : from userContext= " net . kinzan . component . maxparagraphs " / > 



68 

69 </ktp:binding> 

70 <ktp: binding component^" form" attribute^" event "> 

71 <ktp:from literal="Edit " /> 

7 2 </ktp:binding> 

73 <ktp:binding attribute=" title"> 

74 <ktp:from literal="News"/> 

75 </ktp:binding> 

7 6 </ktp:bindings> 
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77 < / ktp : componentMode> 



Lines 59-61 The Display mode uses the TwoVerticalZones widget as its main view. The "list" 
and "form" components are mapped to the top and bottom zones. 

Lines 63-65 The iinkableParagraphList attribute in the "list" component is bound to the 

NewsArticles model bean. Since the NewsArticles model bean is obtained from 
invoking the getArticles method on the ContentFetcher bean, the model bean 
type is an array of Article objects. We need to transform this array of Articles to 
an array of LinkableParagraph objects. This is done by specifying the 

com.kinzan.example.content.transformation.ArticlesToLinkableParagraphs 
transformation. 

Lines 66-69 By default, the maximum number of paragraphs to display is set to 5 unless this 
value is specified in the user's context. 

Lines 70-72 The event attribute of the "form" component is set to "Edit". This is the event that 
will be passed to the State Manager when the submit button is pressed. 



The Category mode uses the DropDownListForm widget for its view. The data is 
obtained from the Category model bean. Unlike the previous mode, this mode 
does not contain nested components. 



78 <ktp:componentMode name=" category" widget =" DropDownListForm'* > 

79 <ktp:bindings> 

80 <ktp: binding widgetAttribute="prompt" > 

81 <ktp:from literal="Please select a new category "/> 

82 </Jctp:binding> 

83 <ktp: binding widgetAttribute=" listPostName"> 

84 <ktp:from literal= " category" /> 

85 </ktp:binding> 

86 <ktp: binding widgetAttribute=" listSize"> 

87 <ktp:from literal=" 1" /> 

88 </ktp:binding> 

89 <ktp: binding widgetAttribute=" event "> 

90 <ktp:from literal="Feed" /> 

91 </ktp:binding> 

92 <ktp: binding widgetAttribute=" options "> 

93 <ktp:from modelBean="Category" /> 

94 </ktp:binding> 

95 <ktp:binding attribute="title"> 
96 



<ktp:from literal="Select Category" /> 
p: binding 
ndings> 

99 </ktp:componentMode> 



97 </ktp:binding> 

98 </ktp:bindings> 
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Line 78 The Category mode is defined and associated with the DropDownListForm. 

Lines 83*85 The selected the list box item is assigned the form name "category". This name 
will be used later on in the state diagram. 

Lines 89-91 The next event is set to "Feed". 

Lines 92-94 The list box is populated with the "Category" model bean. 

The definition of the Feed mode is similar to the Category mode. The data comes 
from the Feed model bean and the next event is set to "Display". Please see the 
content.KApp file for further information. 

To be able to transition from the different component modes and process the 
requests, the news component needs a state diagram. This is how it is defined 
for the news component. 



<ktp:stateDiagram name = "Content " /> 



1 .24.4 News Component State Diagram 

The news component defines three component modes. Each component mode is 
associated with an action state. The action state executes the appropriate edits 
and transitions the component to its next mode. Since the nested components do 
not define the corresponding states, all events are handled by the news 
component state diagram. In this example, all actions are implemented in 
JavaScript. 



1 <ktp:stateDiagram name= "Content" startState= "display" 

2 xmlns : ktp="http : / /www. kinzan . net "> 

3 <Jctp:catch exceptions " java . lang . Exception" state="display" /> 

4 <ktp: components tate name = "display" > 

5 <ktp: transition event="Edit" state="category" /> 

6 </ktp:componentState> 

7 <ktp: components tate name=" category ■> 

8 <ktp: transition event="Feed" state="xSetCategory" /> 

9 </ktp: components tate> 

10 <ktp: components tate name="feed"> 

11 <ktp: transition event=" Display" state='xSetDisplay" /> 

12 </ktp: components tate> 

13 <ktp:actionState name="xSetCategory"> 

14 <ktp: script language=" JavaScript"> 

© 2001 Kinzan Inc. 
Page 108 

KiNZAN 



KTP Developer's Guide 



4348P003Z 



15 userContext . setAttribute ( "category", 

16 actionEvent .getAttribute ( "category" ) ); 

17 actionEvent .setNamet "setCategory" ); 

17 </ktp:script> 

18 <ktp: transition event= " setCategory" state=" f eed" /> 

19 </ktp:actionState> 

20 <ktp:actionState name="xSetDisplay"> 

21 <ktp: script language=" JavaScript "> 

22 userContext . setAttribute ( "feed", 

23 actionEvent . getAttribute ( "feed" ) ); 

34 actionEvent .setName ( "setFeed" ); 

35 </ktp: script> 

36 <ktp: transition event="setFeed* state="display" /> 

37 </ktp:actionState> 

38 </ktp: stateDiagram> 



Lines 13-18 The xSetCategory action state is executed when the news component is in the 
Category component mode and the "Feed" button is pressed. The action takes 
the form variable posted with the name "category" and sets its value into the user 
context. It then generates a "setCategory" event which transitions the news 
component to the Feed component mode. 

Lines 20-37 The xSetDisplay action state is executed when the news component is in the 
Feed component mode and the "Display" button is pressed. This time, the form 
variable "feed" is set into the user context and the component is transitioned to 
the Display mode. 
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<?xml version=" 1 . 0" ?> 

<!DOCTYPE ktp:kapp SYSTEM "http://www.kinzan.net/dtd/kapp.dtd" > 

<ktp:kapp name=" content" xmlns : ktp= "http: / /www. kinzan.net" > 

<!-- Define domains --> 
< k tp : doma i nt> i s t > 

<ktp: domain name="@content. domain© " documentRoot= " content " /> 
< /ktp : domainList> 

<ktp : beanManagerList> 

<ktp : beanManager name= " kinzan : / beanmanager / kinzan/ LocalEJBContainer • /> 
</ktp : beanManagerList> 

<!-- Includes --> 
<ktp: includeList> 

<ktp: include>simplegui . kapp</ktp: include> 

<ktp: include>stylelib.kapp</ktp: include> 
</ktp: includeList> 



<!-- Widgets --> 
<ktp:widgetList> 

<!--A generic list of paragraph, each paragraph may consists of a header, 
header link, text, text link, footer, and footer link. All links are 
optional. If a link is supplied the associated element is made a 
hyperlink. The maxParagraphs attribute limits the number of paragraph 
displayed by this list. The bulletGraphic attribute can be set 
to a name of a gif (Note: It should be an asset) --> 
<ktp : widget name= " HyperLinkableParagraph" > 
<ktp : attributeList> 

<ktp: local name="linkableParagraphList" 

type= "com. kinzan. widget. LinkableParagraph [ ] " /> 
<ktp: local name = "maxParagraphs" type=" java.lang. Integer" 

defaultValue="5"/> 
<ktp: local name="bulletGraphics" type= u java. lang. String" /> 
</ktp:attributeList> 

<ktp:widgetTemplate style=" false" locale=" false"> 

hyperLinkableParagraph . kwt 
< /ktp : widgetTemplate> 
</ktp :widget> 

<!-- Dropdown list form --> 

<ktp : widget name= " DropDownLis tForm" > 

<ktp:attributeList> 

< ktp: local name=" prompt" type=" java. lang. String " /> 

<ktp: local name="listPostName" type=" java. lang. String " /> 

<ktp: local name="listSize" type=" java. lang. String* defaultValue="l"/> 

<ktp:local name="options" type=" java . lang . String [ J "/> 

<ktp: local name=" event" type=" java. lang. String "/> 

</ktp:attributeList> 

<ktp:widgetTemplate style=" false" locale=" false"> 

dropDownListForm.kwt 
</ktp:widgetTemplate> 

</ktp :widget> 
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<!-- An empcy form widget - -> 
<kcp: widget name=" Empty Form" > 

<ktp:attributeList> 

<ktp: local name= "event" type= B java . lang. String" /> 

</ktp:attributeList> 

<ktp:widgetTemplate style= " false" locale=" false"> 

emptyForm. kwt 
< /ktp : widgetTemplate> 
</ktp :widget> 

<!-- Two zone widget --> 

<ktp: widget name= "TwoVerticalZones "> 

<ktp:widgetTemplate style= H false" locale^ false"> 
twoVerticalZones .kwt 

< /ktp : widgetTemplate> 
</ktp:widget> 

</ktp:widgetList> 

<ktp : componentTypeList> 

<!-- A paragraph list component --> 

<ktp:componentType name= H ParagraphList" defaultMode="display"> 

<ktp:description> 

A component that contains a list of paragraphs 
</ktp : description 

<ktp:attributeList> 

<ktp: reference name=" linkableParagraphList" 

widget="HyperLinkableParagraph" 
attribute= " linkableParagraphList" /> 
<ktp: reference name="maxParagraphs" widget="HyperLinkableParagraph* 

attribute= "maxParagraphs " /> 
<ktp: reference name= M bulletGraphics" widget^" HyperLinkableParagraph" 
attribute="bulletGraphic" /> 
</ktp:attributeList> 

<ktp : componentModeList> 

<ktp : componentMode name= "display" widget = " HyperLinkableParagraph" /> 
</ktp:componentModeList> 

< /ktp : componentType> 

<!-- An empty form component --> 

<ktp:componentType name=" EmptyForm" defaultMode=" display" > 

<ktp:description>An empty form component< /ktp: description 

<ktp:attributeList> 

<ktp: reference name= "event" widget=" EmptyForm" attribute= " event " /> 
</ktp:attributeList> 

<ktp:componentModeList> 

< ktp: componentMode name= "display" widget = " EmptyForm" /> 
< /ktp : componentModeList> 

< / ktp : componentType> 

<!-- Syndicated News component --> 

<ktp:componentType name =" News" de f au 1 t Mode ="disp lay "> 
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<ktp:description>This is a very simple news components /ktp: description 

<ktp:attributeList> 

<ktp:local name=" title" type=" java . lang . String 1 * def aultValue= "News" /> 
</ktp:attributeList> 

<!-- Nested components --> 
<ktp : componentList> 

<ktp: component name="list" type="ParagraphList" /> 

<ktp: component name=" f orm" type^EmptyForm'* /> 
< / ktp : componentLis t> 

<!-- Model bean list --> 
<ktp:modelBeanList> 

<!-- Call syndicated content session bean to get News items --> 
<ktp imodelBean name= "News Article s " > 

<ktp:rule name = n SyndicatedCon tent" method="getArticles" /> 

<ktp:param name=" category" type=" java. lang. String" 
defaultValue= H NEWS"> 
<ktp: from userContext=" category" /> 
</ktp:param> 

<ktp:param name="feed" type=" java. lang. String" 
defaultValue="TOP STORIES" > 
<ktp:from userContext=" f eed" /> 
</ktp:param> 

< / ktp : modelBean> 

<!-- Call the syndicated content session bean to get a list 

of categories --> 
<ktp: model Bean name=" Category" > 

<ktp:rule name ="SyndicatedCon tent " method="getCategories" /> 
< / k tp : model Bean> 

<ktp:modelBean name="Feed"> 

<ktp : rule name= " SyndicatedContent " method= " getFeedsFromCategory " /> 
<ktp:param name=" category" type=" java . lang . String" 
def aultValue= "TECHNOLOGY " > 
<ktp:from userContext= "category" /> 
</ktp:param> 
< /ktp : modelBean> 

</ktp:modelBeanList> 



<!-- Modes --> 

<ktp : componentModeList> 

<! — Display --> 

<ktp:componentMode name=" display" widget="TwoVerticalZones"> 

<!-- Map the paragraph list and the empty from into the 

zones for this widget --> 
<ktp:zone name=*top" component =" list " /> 
<ktp:zone name= "bottom" component^ " f orm" /> 

<!-- bindings for these two components --> 
<ktp:bindings> 
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<ktp: binding components" list" attributes " linkableParagraphList" > 
<kxp: from model Bean ="NewsAr tides " 
trans format ion= "com. kinzan. example .content . transformation. ArticlesToLinkableParagraphs" /> 

</ktp:binding> 

<ktp: binding component=" list" attribute= "maxParagraphs" 
def aul tValue= " 5 " > 
<ktp: from userContext = "net . kinzan. component .maxparagraphs" / > 
</ktp: binding> 

<ktp: binding component = " form" attributed event" > 

<ktp:from literals - Edit " /> 
</ktp: binding> 

<ktp:binding attributes" title"> 

<ktp:from literals "News* /> 
</ktp: binding> 

< /ktp : bindings> 

< /ktp : componentMode> 

<!-- Select news category mode --> 

<ktp:componentMode name = "category" widget="DropDownListForm"> 
<ktp:bindings> 

<ktp: binding widgetAttribute= "prompt " > 

<ktp:from literal= " Please select a new category "/> 
< / ktp : binding> 

<ktp : binding widgetAttribute= " 1 istPos tName " > 

<ktp:from literals "category" /> 
</ktp:binding> 

<ktp : binding widgetAttribute= " listSize" > 

<ktp:from literal=U"/> 
</ktp:binding> 

<ktp : binding widgetAttribute= ■ event " > 

<ktp:from literal="Feed" /> 
< /ktp : binding> 

<ktp : binding widgetAttribute= "options " > 

< ktp: from modelBean= "Category " /> 
< /ktp : binding> 

<ktp:binding attributes" title"> 

<ktp:from literal= "Select Category" /> 
</ktp:binding> 

</ktp :bindings> 
< / ktp : componentMode> 

<!-- Select news feed mode --> 

<ktp:componentMode name="feed" widget="DropDownListForm"> 
<ktp: bindings> 

<ktp: binding widgetAttribute= "prompt" > 

<ktp:from literal=-Please select a feed "/> 
</ktp:binding> 

<ktp: binding widgetAttribute= " list Pos tName •> 
<ktp:from literal=" feed" /> 
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</ktp :binding> 

<ktp: binding widgetAttribute="listSize"> 

<ktp:from literal="l° /> 
</ktp : binding> 

<ktp : binding widgetAttribute= "evenc"> 

<ktp:from literal="Display" /> 
</ktp :binding> 

<ktp : binding widgetAttribute= "options " > 

<ktp:from modelBeansTeed" /> 
</ktp:binding> 

<ktp:binding attributed title"> 

<ktp:from literal="Select Feed"/> 
</ktp:binding> 

</ktp:bindings> 
</ktp : componentMode> 



</ktp : componentModeList> 

<!-- Define the component state diagram --> 
<ktp: stateDiagram name = "Content" /> 

< / ktp : componentType> 

</ktp: componentTypeList> 

<ktp:KPDList> 

<ktp:KPD name=** secondComponent " title="SecondComponent"> 
<ktp:description>My Second component</ktp: description 
< ktp : component name="contentComponent" type="News' /> 

</ktp:KPD> 
</ktp:KPDList> 



</ktp:kapp> 

end of file: content. kapp 
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file: Content Fete her Bean. 3 ava 

public class ContentFetcherBean implements SessionBean 
{ 

/** 

* The EJB session context. 
*/ 

private SessionContext iContext; 
/** 

* Gets the news categories that are available from the syndicated news 

* server. 
* 

* ©return an array of strings containing the news categories that are 

* avialable. 

* ©exception ServiceException if the services encounters a problem in 

* performing the request. 

* ©exception LookupException if the service manager can't find the service. 
*/ 

public String [] getCategories ( ) 

throws ServiceException, LookupException 

{ 

AppContext appContext = KinzanApp.GetAppContext ( ) ; 
RemoteContentService service = 

(RemoteContentService) appContext . getService ( RemoteContentService . class ); 

return service .getCategories O ; 

} 

/** 

* Gets the feeds that are available for a given news category. 

* ©return an array of strings containing the name of the feeds. 

* ©exception ServiceException if the services encounters a problem in 

* performing the request. 

* ©exception LookupException if the service manager can't find the service. 
*/ 

public String (] getFeedsFromCategory ( String category ) 
throws ServiceException, LookupException 

{ 

String [] feedsName = null; 

AppContext appContext = KinzanApp .GetAppContext ( ) ; 
RemoteContentService service = 

(RemoteContentService) appContext .getService ( RemoteContentService .class ); 

FeedU feeds = service. getFeedsFromCategory ( category ); 

if ( feeds != null ) 

{ 

feedsName = new String ( feeds. length ]; 
for ( int i = 0; i < feeds . length; i++ ) 
{ 

feedsName [ i ] = feeds [ i l.iName; 

} 

) 

return feedsName; 

) 
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* Gets the news articles given a category and its associated feed. 

* ©return an array of Article objects. 

* ©exception ServiceException if the services encounters a problem in 

* performing the request. 

* ©exception LookupException if the service manager can't find the service 
*/ 

public Articled getArticles( String category. String name) 
throws ServiceException, LookupException 

{ 

AppContext appContext = KinzanApp .GetAppContext ( ) ; 
RemoteContentService service = 

(RemoteContentService) appContext .getService ( RemoteContentService. class ); 

return service. getArticles ( category, name ); 

} 

/** 

* Callback for the ejb container to notify that the bean is being activate 
V 

public void ejbActivate { ) 

{ 

} 

/** 

* Callback for the ejb container to notify the bean that is being removed 
*/ 

public void ejbRemoveO 

{ 

} 

/** 

♦^Callback for the ejb container to notify the bean that is being passivated. 

public void ejbPassivate ( ) 

{ 

) 

/** 

* The EJB containt calls this method to set the ejb session 
*/ 

public void setSessionContext ( SessionContext ctx ) 
< 

iContext = ctx; 

) 

/** 

* The EJB container calls this method to notify the bean that it's being 

* created. 
V 

public void ejbCreateO 

{ 

} 



end of file: Con t en t Pete her Bean. j a va 
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6.Kinzan Glossary 



Term 

Action 



Meaning 



Performs the appropriate e-business rule on behalf of the 
user. 



Adaptive Web Service 



An autonomous business object that logically couples 
presentation, code, and data and thus encapsulates a 
discrete functionality that can be dynamically loaded at 
run time to add that functionality to an Internet or web 
based application. 



Assets 

Branded Assets 

Components 

Containers 



Leaf objects that are included on a page via widgets. 
They include but are not limited to JSP, TXT, HTML, and 
image files. 

Assets with variants that can be resolved dynamically 
based on the current style, locale, and/or target device. 

A logical object or Mini-Application, coupling the model, 
view, and controller for the user. 



Controller Layer 



KApp File 
(Kinzan Application 
File) 

KTP 



KPD 

(Kinzan Page 
Descriptor) 



KSD 



Collections of content and presentation, typically " 
deployed within a page layout. Containers may contain 
components (a.k.a. "Adaptive web services") that contain 
widgets, JSP fragments, other containers, links to 
external resources, or any of these in combination. 



In MVC architecture, the means by which the user 
provides input or changes the state of the model. In KTP, 
the controller layer comprises the state manager, state 
diagrams, and actions. 



An XML file that describes the site and the assets that 
belong to it and is the equivalent of a Makefile. 



Kinzan Technology Platform is a framework that easily 
allows for modular construction of Internet Applications. 

A collection of references to modules that represent style, 
structure, presentation, content, and branded assets. 
Page configuration and assembly instructions are 
captured as XML in the KPD file and used to intelligently 
drive the rendering process. 

An XML file that describes the state flow for the 
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Term 

(Kinzan State Diagram) 
KWT 

(Kinzan Widget 
Template) 

Localization 



Presentation 



Rendering Service 



Service 



Services Manager 
State Diagram 
State Manager 
Style 



Meaning 

component. 

A definition structure for the widgets, including zones 
(placeholders) for content within that structure. 

The elements that make up a KPD collection may need 
the capability to support final JSP's for multiple 
languages. Localization is the method of making your 
application support various countries, languages, and 
dialects at the logic level so that it handles single byte, 
double byte, currency, etc. 

Within each zone of a page layout, various display 
elements are collected into a presentation for that zone. 
Presentation is modeled separately because similar 
content may be presented in different ways in different 
contexts. For example, sales data may be presented in 
graphical form or in a spreadsheet form without changing 
the content. 



Creates the response or resulting html that the user 
consumes by digesting the style, Kinzan Page 
Descriptor, widget and bound data. 

Is a representation of different ways to access 
information and to store information. These include 
databases, messaging services, higher-level application 
components like EJB's, etc. Typically, the main 
challenges in working with services are finding the 
service that provides the information you need, then 
interfacing with that service to retrieve the information. 



Provides an abstraction layer for many kinds of back end 
services and includes the ability to dynamically look up 
and bind to services via name lookup servers. 

Represents discrete steps in an application flow, with 
decision points that trigger transitions to different sections 
of the application. 



Provides basic transaction management across action 
components, and facilitates links to model beans, 
business rules and the Services Manager. 



An XML file that defines style elements to apply to pages 
that reference the style. The format of the style file 
closely follows that used in Cascading Style Sheets 
(CSS), specifying a list of tags and the style attributes for 
each taa. MultiDle classes mav be defined in a stvle. 
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Term Meaning 

These classes allow you to define variations of style 
attributes for given tags. 

Template Collections of common resources and content that apply 

on a site-wide basis. Templates are usually used to 
contain all "brand able" aspects of an offering, so that an 
application may be rapidly private-labeled for different 
partners, and customers may select from multiple 
branding motifs for their site. 

User Context An object of class userContext that tracks the user's 

progress through a site. Information that the userContext 
object contains includes the context ID, the user's current 
state, and the return stack (the user's movement 
between actions). 

Widget A generic or custom control that is purely visual. 
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7. DTD Files 

Following are listings for the DTD files for KApp, KSD, KSec, actionValidator, and 
openejb_conf files. 

File: kapp.dtd 

<! ELEMENT ktp : description (#PCDATA)> 

<! ELEMENT ktp:KPD ( ktp: description, ktp : component) > 

< ! ATTLIST ktp:KPD 

name CDATA ^REQUIRED 

title CDATA # REQUIRED 

visibility CDATA #IMPLIED 

overwriteable CDATA # IMPLIED 

> 

<! ELEMENT ktp:KPDList (ktp:KPD+)> 

< ! ELEMENT ktp:asset (ktp description? , ktp: variant + ) > 
< ! ATTLIST ktp:asset 

name CDATA ^REQUIRED 

overwriteable CDATA #IMPLIED 

visibility CDATA 8IMPLIED 

> 

< ! ELEMENT ktp : attributeList ( (ktp: local* | ktp: reference*) + ) > 
<! ELEMENT ktp : beanManager EMPTY> 
<! ATTLIST ktp: beanManager 
name CDATA # REQUIRED 

> 

<! ELEMENT ktp : beanManagerList (ktp: beanManager +) > 
< ! ELEMENT ktp:binding (ktp:from)> 
<! ATTLIST ktp: binding 

attribute CDATA # IMPLIED 

component CDATA # IMPLIED 

defaultValue CDATA # IMPLIED 

widgetAttribute CDATA #IMPLIED 

overwriteable CDATA #IMPLIED 

> 

< ! ELEMENT ktp : bindings ( ktp : binding* ) > 

< ! ELEMENT ktp : component (ktp: componentList?, ktp: componentModeList?) ?> 
<! ATTLIST ktp: component 

reference CDATA # IMPLIED 

name CDATA # IMPLIED 

type CDATA ft IMPLIED 

style CDATA # IMPLIED 

uniqueName CDATA # IMPLIED 

overwriteable CDATA # IMPLIED 

visibility CDATA # IMPLIED 

> 

<! ELEMENT ktp : componentList (ktp: component +) > 

<! ELEMENT ktp : componentMode ( ktp: zone* , ktp: bindings ?) ?> 

< ! ATTLIST ktp : componentMode 

name CDATA # REQUIRED 

widget CDATA # IMPLIED 

> 

< ! ELEMENT ktp : componentModeList {ktp:componentMode+) > 
<! ELEMENT ktp : componentType 

(ktp description?, (ktp: attributeList? | ktp:modelBeanList? | ktp: componentList?) * , ktp:compone 
ntModeList, ktp: stateDiagram?) > 
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< ! ATTLIST ktp:componentType 
defaultMode CDATA # REQUIRED 
name CDATA # REQUIRED 
style CDATA # IMPLIED 
visibility CDATA # IMPLIED 
overwriteable CDATA ft IMPLIED 
extends CDATA # IMPLIED 

> 

<! ELEMENT ktp : componentTypeList (ktp:componentType+)> 
< ! ELEMENT ktp: domain EMPTY> 
< ! ATTLIST ktp:domain 

documentRoot CDATA # REQUIRED 

name CDATA # REQUIRED 

> 

< ! ELEMENT ktp : domainList {ktp: domain* ) > 
<! ELEMENT ktp: from EMPTY> 
<! ATTLIST ktp: from 

component CDATA # IMPLIED 

attribute CDATA ftlMPLIED 

bundle CDATA ft IMPLIED 

literal CDATA # IMPLIED 

userContext CDATA # IMPLIED 

modelBean CDATA # IMPLIED 

transformation CDATA # IMPLIED 

> 

<! ELEMENT ktp: include (# PCDATA )> 

< ! ELEMENT ktp : includeList (ktp : include* ) > 

<! ELEMENT ktp:kapp 

(ktp: domainList, ktp : beanManagerList? , ktp: includeList?, ktp: styleList?, (ktp :assetList? | ktp: 
widgetList? | ktp : componentTypeList? | ktp : componentList? | ktp : KPDList? ) * ) > 
<! ATTLIST ktp:kapp 

name CDATA # REQUIRED 

visibility CDATA #IMPLIED 

overwriteable CDATA # IMPLIED 

> 

<■ ELEMENT ktp: local EMPTY> 
<! ATTLIST ktp: local 

default Value CDATA ft IMPLIED 

name CDATA # REQUIRED 

type CDATA ft REQUIRED 

required CDATA # IMPLIED 

> 

<! ELEMENT ktp : modelBean (ktp: rule, ktp: param*) > 
<! ATTLIST ktp: modelBean 

name CDATA # REQUIRED 

scope CDATA ft IMPLIED 

> 

< ! ELEMENT ktp:modelBeanList ( ktp: mode lBean+ ) > 
<! ELEMENT ktp: param (ktp: from) > 
<! ATTLIST ktp: param 

default Value CDATA ft IMPLIED 

name CDATA ft REQUIRED 

type CDATA # REQUIRED 

> 

<! ELEMENT ktp : reference EMPTY> 
<! ATTLIST ktp: reference 

attribute CDATA ft IMPLIED 

name CDATA # IMPLIED 

widget CDATA ft IMPLIED 

component CDATA # IMPLIED 

defaultValue CDATA #IMPLIED 

required CDATA ft IMPLIED 
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< ! ELEMENT ktp: rule EMPTY> 
< ! ATTLIST ktp: rule 

method CDATA ft REQUIRED 

name CDATA ft REQUIRED 

> 

<! ELEMENT ktp : s tateDiagram EMPTY> 
< ! ATTLIST ktp : s tateDiagram 
name CDATA # REQUIRED 

> 

<■ ELEMENT ktp: style ( ktp : description? ) > 
<! ATTLIST ktp: Style 

file CDATA # REQUIRED 

name CDATA # REQUIRED 

visibility CDATA 8 IMPLIED 

overwriteable CDATA # IMPLIED 

> 

<! ELEMENT ktp : s tyleList (ktp : style+ ) > 
<! ELEMENT ktp: widget 

(ktp :descr iption? , ktp : attributeList? , ktp : widgetAssetList? , ktp iwidgetTemplate) > 
< ! ATTLIST ktp : widget 

name CDATA # IMPLIED 

visibility CDATA # IMPLIED 

> 

< ! ELEMENT ktp : widgetAssetList (ktp: widgetAsset*) > 
<! ELEMENT ktp : widgetList (ktp: widget+) > 
< ! ELEMENT ktp : widgetTemplate (»PCDATA)> 
<! ATTLIST ktp: widgetTemplate 

locale CDATA "true" 

style CDATA "true" 

target CDATA "true" 

> 

< ! ELEMENT ktp : zone EMPTY > 
<! ATTLIST ktp: zone 

component CDATA # REQUIRED 

name CDATA # REQUIRED 

> 

<! ELEMENT ktp: variant (# PCDATA) > 
< [ATTLIST ktp: variant 

locale CDATA "true" 

style CDATA "true" 

target CDATA "true" 

> 

<! ELEMENT ktp : assetList (ktp : asset*) > 
< ! ELEMENT ktp : widgetAsset EMPTY> 
<! ATTLIST ktp: widgetAsset 

asset CDATA # REQUIRED 

name CDATA # REQUIRED 

overwriteable CDATA ^IMPLIED 

> 
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file: ksd.dtd 



<! ELEMENT ktp : stateDiagram 

(ktp:actionState* , ktp :displayState* , Jctp: components tate* , ktp : transition* , ktp: catch*) 
< ! ATTLIST ktp: stateDiagram 

name CDATA # REQUIRED 

startState CDATA ft IMPLIED 

directAccess ( true | false) 'true' 

visibility (public | private | final) 'publio 

<! ELEMENT ktp : displayState (ktp : transition* , ktp :property* ) *> 
< ! ATTLIST ktp:displayState 

name CDATA ftREQUIRED 

forward CDATA ft IMPLIED 

redirect CDATA ftlMPLIED 

kpd CDATA ft IMPLIED 

permission CDATA ftlMPLIED 

directAccess ( true | false) 'true' 

visibility (public | private | final) 'public' > 

<! ELEMENT ktp : componentState (ktp: transition* , ktp : property* ) *> 
< ! ATTLIST ktp : componentState 

name CDATA ft REQUIRED 

permission CDATA ftlMPLIED 

directAccess ( true] false) 'true' 

rethrowEvent (true [false) 'false' 

visibility (public (private | final) 'public '> 

< ! ELEMENT ktp : actionState ( ktp : transition* , ktp : catch* , ktp : property* , ktp : script? ) *> 
<! ATTLIST ktp: actionState 

name CDATA ft REQUIRED 

action CDATA ftlMPLIED 

script CDATA ftlMPLIED 

permission CDATA ftlMPLIED 

directAccess ( true | false) 'true' 

visibility (public | private | final) ' public ' > 



<! ELEMENT ktp: script (# PCDATA) > 
<! ATTLIST ktp: script 

language CDATA ftREQUIRED> 

<! ELEMENT ktp: property EMPTY> 

<! ATTLIST ktp: property 

name CDATA ft REQUIRED 
value CDATA #REQUIRED> 



<! ELEMENT ktp : trans i t ion ( ktp: property* ) > 
< (ATTLIST ktp: transition 

event CDATA ft REQUIRED 

State CDATA ft REQUIRED 

wizard CDATA ftlMPLIED 

clearContext ( true | false) ' false* > 

<! ELEMENT ktp: catch EMPTY> 
<! ATTLIST ktp: catch 

exception CDATA ft REQUIRED 

state CDATA ftREQUIRED 

wizard CDATA ft IMPLIED> 

end of file: ksd.dtd 
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file: fcsec.dtd 

<! ELEMENT ktp: ACL 
EMPTY > 

< ! ATTLIST ktp: ACL 

componentUniqueName CDATA 8IMPLIED> 

<! ELEMENT ktp:appRole 

(ktp: role+) > 
< ! ELEMENT ktp : componentACL 

(ktp:ACL+) > 
< ! ELEMENT ktp : componentAccess 

EMPTY> 



<! ATTLIST ktp: componentAccess 
allaccess CDATA #IMPLIED> 

<! ATTLIST ktp: componentAccess 
componentUniqueName CDATA #IMPLIED> 
<! ELEMENT ktp : component Permission 
(ktp permission?) > 

< ! ATTLIST ktp : componentPermission 
allpermission CDATA #IMPLIED> 

<! ATTLIST ktp: componentPermission 
componentUniqueName CDATA #IMPLIED> 
<! ELEMENT ktp : ksec 

( ktp : componentACL? , ktp : appRole) > 

<! ATTLIST ktp: ksec 

xmlns:ktp CDATA # IMPLIED 

name CDATA #REQUIRED> 
<! ELEMENT ktp : permission 
EMPTY> 

<! ATTLIST ktp: permission 
name CDATA #IMPLIED> 
<! ELEMENT ktp: role 

( ktp : componentAccess * , ktp : component Permiss ion* ) 

<! ATTLIST ktp: role 
name CDATA #IMPLIED> 

end of file: ksec.dtd 
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file: actionValidator.dtd 

<?xml encoding="US-ASCII B ?> 

<! ELEMENT ktp:actionValidator ( ktprparameterSet* , ktp: parameter* ) *> 
< ! ATTLIST ktpractionValidator 

class CDATA #IMPLIED> 

<! ELEMENT ktp:parameterSet ( ktp : parameter* ) > 
<! ATTLIST ktp:parameterSet 

name CDATA #REQUIRED> 

< ! ELEMENT ktp : parameter (ktp:validator*) > 
<! ATTLIST ktp: parameter 

name CDATA # REQUIRED 

nullOkay (true] false} ' false ' > 

< ! ELEMENT ktp : val idator ( ktp : property* ) > 
<! ATTLIST ktp: validator 

type CDATA #REQUIRED> 

<! ELEMENT ktp: property EMPTY> 
<! ATTLIST ktp: property 

name CDATA # REQUIRED 

value CDATA #REQUIRED> 

end of file: actionValidator.dtd 
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file: open© jb_conf ig.dtd 

<?xml encoding= "US-ASCII "?> 

<!-- Sid: openejb_conf ig.dtd, v 1.20 2000/12/16 14:55:29 rmonson Exp $ --> 



< ! ELEMENT entity-bean (description?, display-name? , smal 1- icon? , large- icon? , ejb- 
deployment-id, home, remote, ejb-class, primary-key, jndi-enc?, security-role-ref * ) > 
<! ELEMENT entity-container (description?, display-name?, container-name, properties?, 
entity-bean+) > 

<! ELEMENT codebase (# PCDATA) > 
<! ELEMENT class-name (#PCDATA)> 
<! ELEMENT connection (properties) > 

<! ELEMENT connectors (connector*, connection-manager* ) > 

<! ELEMENT connector (connector- id, connection-manager- id, managed-connection- factory) > 

<! ELEMENT connector- id (# PCDATA) > 

<! ELEMENT connection-manager- id (# PCDATA )> 

<! ELEMENT connection-manager (connection-manager- id, class-name, properties?) > 
<! ELEMENT managed-connection- factory (class-name, properties?) > 

< ! ELEMENT containers (stateful-session-container | stateless-session-container | entity- 
container) +> 

<! ELEMENT container-name (#PCDATA)> 

<! ELEMENT container-system (containers, security-role+, method-permission*, method- 
transaction+) > 

<! ELEMENT description (#PCDATA)> 

<! ELEMENT display-name (#PCDATA)> 

<! ELEMENT ejb-class <#PCDATA)> 

<! ELEMENT ejb-deployment-id (#PCDATA)> 

<! ELEMENT ejb-ref (ejb-ref -name, home, ejb-ref -location) > 
<! ELEMENT ejb-ref- location (ejb-deployment-id | connections 
<! ELEMENT ejb-ref -name (#PCDATA)> 
<! ELEMENT home { # PCDATA) > 

<! ELEMENT env-entry (env- en try -name, env- en try -type , env-entry-value) > 
<! ELEMENT env- en try -name (#PCDATAJ> 
<! ELEMENT env-entry- type (#PCDATA)> 
<! ELEMENT env-entry-value (#PCDATA)> 

<! ELEMENT facilities ( intra- vm-server , connectors?, services )> 
<! ELEMENT factory-class (#PCDATA)> 

< ! ELEMENT intra-vm-server (proxy- factory, codebase, properties?) > 

<! ELEMENT jndi-enc (env-entry*, ejb-ref*, resource-ref *) > 

<! ELEMENT large- icon (# PCDATA )> 

<! ELEMENT logical -role-name (#PCDATA)> 

< !-- 

The method element is used to denote a method of an enterprise bean's 
home or remote interface, or a set of methods. The ejb-deployment-id element 
must be the id of one of the enterprise beans declared in the 
container -system; the optional method-intf element allows to 
distinguish between a method with the same signature that is defined in 
both the home and remote interface; the method-name element specifies 
the method name; and the optional method-params elements identify a 
single method among multiple methods with an overloaded method name. 

There are three possible styles of the method element syntax: 

1 . <method> 

<me t hod- name > *< /me t hod- name > 
</method> 
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This style is used to refer to all the methods of all 
deployments (home and remote interfaces) in a container-system. 

2 . <method> 

<me t hod - name >METHOD</ met hod- name > 
</method> 

This style is used to refer to the specified method in all 
deployments in the container-system. If there are multiple methods with 
the same overloaded name (home and remote interfaces), the element of 
this style refers to all the methods with the overloaded name. 

3 . <method> 

<method-name>METHOD< /method- name> 
<method-params> 

<method-param> PARAM- 1< /method-param> 

<method-param> PARAM-2</method-param> 

<method-param> PARAM-n< /method-param> 
< /method-params> 
<method> 

This style is|used to refer to a single method within a set of 
methods (home and remote interfaces) with an overloaded name for all 
deployments in a container-system. PARAM- 1 through PARAM- n are the 
fully-qualified Java types of the method's input parameters (if the method 
has no input arguments, the method-params element contains no method-param 
elements). Arrays are specified by the array element's type, followed by 
one or more pair of square brackets (e.g. int [ ] ( ] ) . 



The optainal ejb-deployment-id element can be used to narrow the scope of the 
declaration to one specific deployment within the container- system. 
If an ejb-deployment-id is not specified, the declaration applies to all 
matching bean methods {home and remote interface) in all deployments. 

The optional method- intf element can be used when it becomes 
necessary to differentiate between a method defined in the home 
interface and a method with the same name and signature that is 
defined in the remote interface. 

--> 

<! ELEMENT method (description?, ejb-deployment-id?, method-intf ? , method-name, method- 
params?) > 

<! ELEMENT method-intf ( # PCDATA) > 

<! ELEMENT method-name (#PCDATA)> 

< ! ELEMENT method-param (#PCDATA)> 

<! ELEMENT method-params (method-param* ) > 

<! ELEMENT method-permission (description?, role-name+, method+)> 
< ! 

The method- transaction element specifies how the container must 
manage transaction scopes for the enterprise bean's method invocations. 
The element consists of an optional description, a list of method 
elements, and a transaction attribute. The transaction attribute is to 
be applied to all the specified methods. 

Used in: container- system 

Maps to: container- transaction ejb-jar_l_l 
- - > 

<! ELEMENT method- transaction (description?, method*, trans-attribute) > 
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<! ELEMENT openejb ( container-system, faciiities>> 
<! ELEMENT physical -role -name (#PCDATA>> 
< ! ELEMENT primary-key (ff PCDATA) > 
<! ELEMENT properties ( proper ty+)> 

<! ELEMENT property ( property- name , property-value) > 

< ! ELEMENT proper ty- name { # PCDATA ) > 
<! ELEMENT property- value {#PCDATA)> 
<! ELEMENT proxy- factory (# PCDATA) > 

<! ELEMENT role-mapping ( logical-role-name+ , physical -role- name + ) > 

< ! ELEMENT role-name { if PCDATA) > 

< ! -- 

The role-link element is used to link a security role reference to a 
defined security role. The role-link element must contain the name of 
one of the security roles defined in the security-role elements. 
Used in: security-role-ref 
--> 

<! ELEMENT role- link (# PCDATA) > 



<! ELEMENT remote (#PCDATA)> 

< ! -- 

The res-auth element specifies whether the enterprise bean code signs 
on programmatically to the resource manager, or whether the Container 
will sign on to the resource manager on behalf of the bean. In the 
latter case, the Container uses information that is supplied by the 
Deployer . 

The value of this element must be one of the two following: 

<res-auth>Application</res-auth> 

<res -auth>Container < / res -auth> 

Mapps to: res-auth ejb- jar__l_l 

--> 

<! ELEMENT res-auth <#PCDATA)> 

< ! — 

The res- id maps to a connector- id in the corresponding connectors section. For example a 
JDBC DataSource resource-re f would be supported by a connector and its res -id would map 
to the connector-id in connector declaration. 
Used in: resource-ref 
--> 

< ! ELEMENT res- id (#PCDATA)> 

< ! -- 

The res-ref-name element specifies the name of a resource manager con-nection 

factory reference. 

Used in: resource-ref 

Mapps to: res-ref-name ejb-jar_l_l 

--> 

<! ELEMENT res-ref-name (#PCDATA)> 

< ! 

The res -type element specifies the type of the data source. The type 

is specified by the Java interface (or class) expected to be imple-mented 

by the data source. 

Used in: resource-ref 

Mapps to: res -type ejb-jar_l_l 

--> 

<! ELEMENT res -type {# PCDATA) > 
< ! -- 

The resource-ref element contains a declaration of enterprise bean's 
reference to an external resource. It consists of an optional description, 
the resource factory reference name, the indication of the 
resource manager connection factory type expected by the enterprise 
bean code, the type of authentication (bean or container), and either a 
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res-id which maps to the corresponding services res-id. or a set of properties 

Used in: jndi-enc 

Example: 

<resource-ref> 

<res-ref -name>comp/env/ jdbc/Employee</res-ref -name> 
<res - type> j avax . sql . Da taSource< / res - type> 
<res-auth>Container</res-auth> 
<properties> 
<property> 

<property-name>url< /proper ty-name> 
<property-value> jdbc : odbc : orders< /proper ty-value> 
< /proper ty> 
<property> 

<property-name>username< / proper ty-name> 
<property-value>Admin< /proper ty-value> 
< /proper ty> 
<property> 

<property-name>password< /proper ty-name> 
<property-value>< /proper ty-value> 
< /proper ty> 
</properties> 
< /resource- re f > 

Mapps to: resource-ref ejb-jar_l_l 
--> 

< ! ELEMENT resource-ref (description?, res-ref -name, res-type, res-auth, (res-id | 
properties | connector-id) ) > 

< ! ELEMENT resource (description?, res-id, properties)> 

<! ELEMENT security-role (description?, role-name) > 
<! — 

The security-role-ref element contains the declaration of a security 

role reference in the enterprise bean's code. The declaration con-sists 

of an optional description, the security role name used in the 

code, and an optional link to a defined security role. 

The value of the role-name element must be the String used as the 

parameter to the EJBContext . isCallerlnRole (String roleName) method. 

The value of the role- link element must be the name of one of the 

security roles defined in the security-role elements. 

Used in: entity and session 

--> 

<! ELEMENT security- role-ref (description?, role-name, role-link) > 

< ! ELEMENT security-service (description?, display-name?, service-name, factory-class, 

codebase, properties?, role-mapping+ ) > 

<! ELEMENT security-service-name (#PCDATA)> 

<! ELEMENT services (security- service, transaction-service) > 
<! ELEMENT service-name (#PCDATA)> 
< ! ELEMENT small- icon ( # PCDATA ) > 

<! ELEMENT statef ul-bean (description?, display-name?, small- icon?, large-icon?, ejb- 
deployment-id, home, remote, ejb-class, transaction- type, jndi-enc?, security-role-ref *) > 
< ! ELEMENT stateless-bean (description?, display-name?, small-icon?, large- icon?, ejb- 
deployment-id, home, remote, ejb-class, transaction- type, jndi-enc?, security-role-ref *) > 
<! ELEMENT statef ul-session-container (description?, display-name?, container -name, 
properties?, stateful-bean+) > 

<! ELEMENT stateless-session-container (description?, display-name?, container -name, 
properties?, stateless-bean+) > 

<! ELEMENT transaction-service (description?, display-name?, service-name, factory-class, 
codebase , proper t ies ? ) > 

<! ELEMENT transaction-service-name (SPCDATA)> 
< ! ELEMENT transaction- type (#PCDATA)> 

<! — 
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The trans -attribute element specifies how the container must manage the 
transaction boundaries when delegating a method invocation to an 
enterprise bean's business method. 

The value of trans-attribute must be one of the following: 
<trans-attribute>NotSupported</trans-attribute> 
< trans -at tribute>Supports</trans-attribute> 
<trans-attribute>Required</trans-attribute> 
<trans-attribute>RequiresNew</trans-attribute> 
< trans -at tribute>Mandatory< /trans -at tribute> 
<trans-attribute>Never</trans-attribute> 

<trans-attribute>Bean</trans-attribute> (indicates bean managed transaction. 
Stession beans only) 
Used in: method- transaction 
Maps to: trans-attribute ejb-jar_l_l 
--> 

end of file: openejb_conf ig.dtd 
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In the foregoing, the method and apparatus of the present invention is described 
with reference to specific exemplary embodiments thereof. It will, however, be evident 
that various modifications and changes may be made thereto without departing from 
the broader spirit and scope of the present invention. In particular, the separate blocks 
of the various block diagrams represent functional blocks of methods or apparatuses 
and are not necessarily indicative of physical or logical separations or of an order of 
operation inherent in the spirit and scope of the present invention. For example, the 
various blocks of some figures or illustrations may be integrated into components, or 
may be subdivided into components. Moreover, the various blocks of other figures or 
illustrations represent portions of a method which, in some embodiments, may be 
reordered or may be organized in a parallel or a linear or step-wise fashion. The 
present specification and figures or illustrations are accordingly to be regarded as 
illustrative rather than restrictive. 
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CLAIMS 

What is claimed is that which has been described in the foregoing and 
equivalents thereof. 
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